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Customer Satisfaction 

If you discover physical defects in the manuals distributed with a Lisa product 
or in the media on which a software product is distributed, Apple will replace 
the documentation or media at no charge to you during the 90-day period 
after you purchased the product. 



Product Revisions 

Unless you have purchased the product update service available through your 
authorized Lisa dealer, Apple cannot guarantee that you will receive notice of 
a revision to the software described in this manual, even if you have returned 
a registration card received with the product You should check periodically 
with your authorized Lisa dealer. 



Linrutation on Warranties and Liability 

All implied warranties concerning this marwal and media, including implied 
warranties of merchantability and fitness for a particular purpose, are limited 
in duration to ninety (90) days from the date of original retail purchase of tbis 
product 

Even though Apple has tested tiie software described in triis manual and 
reviewed its contents, neither Apple nor its software suppliers make any 
warranty or representation, either express or implied, witb respect to this 
manual or to the software described in this manual, their quality, performance, 
merchantability, or fitness for any particular purpose. As a result, tbis 
software and manual are sold "as is," and you the purchaser are assuming the 
entire risk as to their quality and performance. 

In no event will Apple or its software sipplien be li^le for direct, indirect, 
special, incidental, or consequential damages resulting from any defect in the 
software or manual, even if they have been advised of the possibility of such 
damages. In particular, they shall have no liability for any programs or data 
stored in or used with Apple products, ircluding the costs of recovering or 
reproducing these programs or data 

The warranty and remedies set forth above are exclusive and In lieu of all 
others, oral or written, express or implied. No Apple dealer, a^nt or 
employee is authorized to make any modification, extension or addition to this 
warranty. 

Some states do not allow the exclusion or limitation of implied warranties or 
liability for incidental or consequential damages, so the atoove limitation or 
exclusicffi may not ^ply to yoa This warranty gives you specific legal rights, 
and you may also have other ri^ts that vary from state to state. 
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License and Copyri^t 

This manual and the software (computer programs) described in it are copy- 
rioted by Apple or by Apple's software suppliers^ with all ri^ts reserved^ arid 
they are covered by the Lisa Software License Agreement signed by each Lisa 
owner. Under the copyri^t laws aid the License Agreement, this manual or 
the programs may not be copied, in whole or in part, withcwt the written 
consent of Af^le, exc^t in the normal use of the software or to make a 
backup copy. This exa^eption does not allow copies to be made for others, 
whether or not sold, but all of the material purchased (with all backup cqsies) 
may be sold, given, or loaned to other persons if they agree to be bound by 
the provisions of the License AgreemenL Copying includes translating into 
another language or format 

You may use the software on any computer owned by you, but extra cqpies 
cannot be made for this purpose. For some products, a multiuse license may 
be purchased to allow the software to be used on more than one computer 
owned by the purchaser, including a shared-disk system. (Contact your 
authorized Lisa dealer for more information on multiuse liconses.) 
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This manual is intended for Pascal programmers. It describes an implemen- 
tation of Pascal for the Lisa computer. The compiler and code generator 
translate Pascal source text to MC68000 object code. 

The language is reasonably compatible with Apple II and Apple III Pascal. See 
Appendix A for a discussion of the differences between these forms of Pascal. 

In addition to providing nearly all the features of standard Pascal, as described 
in the Pascal User MaiuaJ ancf Report (Jensen and Wirth), this Pascal provides 
a variety of extensions. These are summarized in Appendix A. They include 
32-blt integers, an otherwise clause in case statements, procedural and 
functional parameters with type-checked parameter lists, and the • operator 
for obtaining a pointer to an object. The real arithmetic conforms to many 
aspects of the proposed IEEE standard for single-precision arithmetic. 

Operating Environment 

The compiler win operate In any standard Lisa hardware configuration; this 
manual assumes the Workshop software environment 

Related Documents 

Pascal User Manual and Report, Jensen and Wlrth, Springer- Verlag 1975. 

Workshop User's Guide for the Us^ Apple Computer, Inc. 1983. 
Other Lisa documentation. 

Definitions 

For the purposes of this manual the following definitions are used: 

• Error: Either a run-time error or a compiler error. 

• Sccipe: The body of text for which the declaration of an Identifier or 
label Is valid. 

• Undefined: The value of a variable or function when the variable does not 
necessarily have a meaningful value of Its type assigned to It 

• (Ji^oeclfled: A value or action or effect that, although possibly 
well-defined. Is not specified and may not be the sanne in all cases or for 
all versions or confl^ratlons of the system. Any programming construct 
that leads to an unspecified result or effect Is not supported. 

Notation and Syntax Diagrams 

All numbers In this manual are In decimal notation, except where hexadecimal 
notation Is specifically Indicated. 

Throughout this manual, bold-face type is used to distinguish Pascal text from 
English text. For example, sqr(n (flv 16) represents a fragment of a Pascal 
program. Sometimes the same word appears both In plain text and In 
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Dold-face; for example, "TlTe declaration of a Pascal procedure begins with 
the word procedure." 

Italics are used when technical terms are introduced. 

Pascal syntax is specified by diagrams. For example, the following diagram 
gives the syntax for an identifier: 



identifier 



letter 






T 



v., 


letter 


^ -^ 


^ 






digit 


^ > 










underscore 


^ 



Start at the left and follow the arrows through the diagram. Numerous paths 
are possible. Every path that begins at the left and ends at the arrow-head on 
the right is valid, and represents a valid way to construct an identifier. The 
boxes traversed by a path through the diagram represent the elements that can 
be used to construct an identifier. Thus the diagram embodies the following 
rules: 

• An identifier must begin with a letter, since the first arrow goes directly to 
a box containing the name "letter." 

• An identifier might consist of nothing but a single letter, since there is a 
path from this box to the arrow-head on the right, without going through 
any more boxes. 

• The initial letter may be followed by another letter, a digit or an 
underscore, since there are branches of the path that lead to these boxes. 

• The Initial letter may be followed by any number of letters, digits, or 
underscores, since there is a loop In the path. 

A word contained in a rectangular box may be a name for an atomic element 
like "letter" or "digit," or it may be a name for some other syntactic 
construction that is specified by another diagram. The name in a rectangular 
box is to be replaced by an actual Instance of the atom or construction that it 
represents, e.g. "3" for "digit" or "counter" for "variable-reference". 

Pascal symtjois, such as reserved words, operaton, and punctuation, are 
bold-face and are enclosed In circles or ovals, as in the following diagram for 
the construction of a compound-statement: 



compound-statement 
» ( begin) 



c 



statement 



O 



T 



*(&rtiy- 
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Text In a circle or oval represents itself, and is to be written as shown (except 
that capitalization of letters is not significant). In the diagram above, the 
semicolon and the words begin and end are symbols. The word "statement" 
refers to a construction Uiat has its own syntax diagram. 

A compound-statement consists of the reserved word begin, followed by any 
number of statements separated by semicolons, followed by the reserved word 
end. (As will be seen in Chapter 6, a statement may be null; thus begin end is 
a valid compound-statement) 
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NOTES 



Chapter 1 
Tokens and Constants 



Ll Character Set and Special Symbols 1-1 

L2 IdenUfiers 1-2 

13 Directives 1-2 

L4 Numben 1-2 

L5 Labels 1-4 

L6 Quoted Stiing Constants 1-4 

1.6.1 Quoted Character Constants 1-4 

1.7 Constant Declarations 1-5 

L8 Comments and Compiler Commands 1-5 
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Tokens are the smallest meaningful units of text In a Pascal program; 
structurally, they correspond to the words In an English sentence. The tokens 
of Pascal are classified into specJaJ symbols, icienUfJers, numOers, labels, and 
quo tea string constants 

The text of a Pascal program consists of tokens and sepa/atorsja separator is 
either a blank or a comment Two adjacent tokens must be separated by one 
or more separators, if both tokens are identifiers, numbers, or reserved words. 

No separators can be embedded within tokens, except in quoted string 
constants. 

1.1 Character Set and Special Symbols 

The character set used by Pascal on the Lisa Is 8-bIt extended ASCII, with 
characters represented by numeric codes in the range from to 255. 

Letters, digits, hex-digits, and blanks are subsets of the character set: 

• The letters are those of the English alphabet, A through Z and a through z. 

'' The aiglts are the Arabic numerals through 9; the hex-digits are the 
Arabic numerals through 9, the letters A through F, and the letters a 
through f. 

• The t)lanks are the space character (ASCII 32), the horizontal tab character 
(ASCII 9), and the CR character (ASCII 13). 

Special sjvWols and reserved woids are tokens having one or more fixed 
meanings. The following single characters are special symbols: 



The following character pairs are special symbols: 

<> <= >= : = . , (» ») 
The following are the reserved words: 



{ >$ 



and 


end 


label 


program 


until 


aiiay 


file 


methods* 


record 


uses 


begin 


for 


mod 


repeat 


var 


case 


function 


nil 


set 


While 


const 


goto 


not 


string 


with 


creation* 


if 


of 


subclass* 




div 


implementation 


or 


then 




downto 


in 


otherwise 


to 




do 


interface 


packed 


type 




else 


intrinsic* 


procedure 


unit 
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Trie reserved words marked with asterisks are reserved for future use. 
Corresponding upper and lower case letters are equivalent in reserved words. 
Only the first 8 characters of a reserved word are significant 

1.2 Identifiers 

Identifiers serve to denote constants, types, variaPles, procedures, functions, 
units and programs, and fields in records. Identifiers can be of any length. Put 
only the first 8 characters are significant. Corresponding upper and lower case 
letters are equivalent In identifiers. 



JaentJrler 



^ letter 









^ 


letter 


^ '^ 


^ 






digit 


,g -J 


■1 






1 


underscore 


^ 



NOTE 



The first 8 characters of an identifier must not match the first 8 char- 
acters of a reserved word. 



Examples of laentJffers: 



Rome 



They 



god SUM get_byte 

13 Directives 

Directives are words that have special meanings In particular contexts, 
are not reserved and can be used as identifiers in other contexts. For 
example, the word forward is interpreted as a directive if it occurs 
immediately after a procedure-heading or function-heading, but in any other 
position it is Interpreted as an identifier. 

L4 Numbers 

The usual decimal notation is used for nunrrtDers that are constants of the data 
types Integer, longint, and real (see section 3.1.1). Also, a hexadecimal integer 
constant uses the $ character as a prefix (1-4 digits for Integer, 5-8 digits for 
longint). 



cfJalt-seoiimoe 



Z 



digit 



J 



hex-djgjt-seouence ^ ^ .. ,. ^ 




^^ ) 
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unsicpied-inteQer 




digit-sequence 



hex-digit-sequence 



J 



sign 



•G> 




unsigned-real 

— ► digit-sequence ^yKly^ digit-sequence 



T 



-^^^ scale-factor -^ 



scale-factor 



<D 




sign 



digit-sequence 



unsigned-number 



x^ 



unsigned-integer 



unsigned- real 



signed-numtier 



\r—\J * 

^* sign — ^ 



unsigned-number 



The letter E or e preceding the scale in an unsigned-real means "times ten to 
the power of". 

Exanples of numbers: 

1 +100 -0.1 5E-3 87.356+8 $ft05D 

Note that 5E-3 means 5x10"^, and 87.35e+8 means 87.35x10®. 
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1.5 Labels 

A label is a digit-sequence in the range from through 9999. 

1.6 Quoted String Ccxistants 

A quoted-strlng-constant Is a sequence of zero or more characters, all on one 
line of the program source text and enclosed by apostrophes. Currently, the 
maximum number of characters is 255. A quoted-string-constant with nothing 
between the apostrophes denotes the null string. 

If the quoted-string-constant is to contain an apostrophe, this apostrophe must 
be written twice. 



Quotecf-stn'r^-constant 



r 



string-character 



i:^ 



o^ 



strlng-cnaracter 



&7y char except (j^ arCR 



7" 



<>-<:> 



Exanrples of quoteO-strJrKi-const&its: 
'Pascal* 'THIS IS A STRING' 
'A* 



•Don"t worry!' 



Ail String values have a lengtn attribute (see Section 3.1.1.6). In the case of a 
string constant value the length is fixed; it is equal to the actual number of 
characters in the string value. 

1.6.1 Quoted Character Constants 

Syntactically, a quoted-character-constant is simply a quoted-string-constant 
whose length is exactly 1. 



Quoteo-ctiaracter-constant 



<\/j — ► [ string-character — ^Qy — ^ 



A quoted-character-constant is compatible with any char-type or string-type; 
that Is, it can be used either as a character value or as a string value. 
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1.7 Constant Declarations 

A constant-declaration defines an identifier to denote a constant, witnin the 
block that contains the declaration. The scope of a constant-identifier (see 
Chapter 2) does not include its own declaration. 

constant-declaration 



constant 



T 



^ slanW 



"•^ slgned-numDer 



^ quoted-string 



quoiea-char 



constant-identifier 



> 



k. 



NOTE 



A constant-identifier is an identifier that has already been declared to 
denote a constant. 



A constant-identifier following a sign must denote a value of type integer, 
longlnt, or real. 

1.8 Comments and compiler commands 

The constructs: 

{ any text not containing right-brace } 

(» any text not containing star-right-paren ») 

are called conwents 

A compiler command is a comment that contains a $ character immediately 
after the { or (» that begins the comment. The $ character is followed by the 
mnemonic of the compiler command (see Chapter 12). 

Apart from the effects of compiler commands, the suDstltution of a blank for a 
comment does not alter the meaning of a program. 

A comment cannot be nested within another comment formed with the same 
kind of delimiters. However, a comment formed with {...} delimiters can be 
nested within a comment formed with (*...») delimiters, and vice versa. 
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2.1 DefinitiGnofaBlock 2-1 
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2.2.3 Position of Declaration within Its Block 2-3 

2.2A Redeclaration within a Block 2-3 

2.2.5 Identifiers of Standard Objects 2-4 
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2.1 DeflniUon of a Block 

A block consists of declarations and a statement-part. Every block is part of 
a procedure-declaratioa a function-declaration, a program, or a unit. All 
identifiers and labels that are declared in a particular block are JocaJ to that 
block. 



block 



■^ 



r- 



^ constant-declaration-part 



r 



""*> type-declaration-part 



label-declaration-part 



D 



^ 



"■^ variable-declaration-part 



^ 
^ 

< 



procedure-and-function-declaration-part 



D 



^ statement-part 



The l^el-cfeclaratJon-part6ec\Skxez all labels that mark statements In the 
corresponding statement-part. Each label must mark exactly one statement in 
the statement-part. 



label-declaiatlcn-pa/t 



<^> 



7 — *|J*5|J — ^ 



<!> 



label 



> digit-sequence 
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The constant-cleclaraUon-partcQvx.'^r\% all constant-declarations local to the 
block. 



caistant-iJeclaraUon-part 
»( ^const^ 



I 



constant-declaration 



J 



The type-declaraUon-part CQViX^im all type-declarations local to the block. 

ty^-declaraUon-part 
»( ^type^ 



Z 



type-declaration ■ 



J 



The i/anaOJe-cfeclaraUon-panQor{X.B\T\% all variable-declarations local to the 
block. 



vafisiJle-declaraUon-part 



-»( var )- 



I 



variable-declaration 



J 



The proceclure-anc/-functJon-cfeclaraU'on-partcovX'a\m all procedure and 
function declarations local to the block. 



pnxeckJW-arxl-funcUon-cleclaraUon-part 
T 



w 



procedure-declaration 



"T 



function-declaration 



The statement-part %'^^z\^\^% the algorithmic actions to be executed upon an 
activation of the block. 



statement-part 



^ compound-statement 
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NOTE 

At run time, all variables declared within a particular block have 
unspecified values each time the statement-part of the tDlock is entered. 

2.2 Rules of Scope 

This chapter discusses the scope of objects wJttiJn tne program or unit In wtilcti 
they are deflnea See Chapter 9 for the scope of objects defined in the 
interface-part of a unit and referenced in a host program or unit. 

2.2.1 Scope of a Declaration 

The appearance of an identifier or label in a declaration defines the identifier 
or label. All corresponding occurrences of the identifier or label must be 
within the scope of this declaration. 

This scope is the block that contains the declaration, and all blocks enclosed 
by that block except as explained in Section 2.2.2 below. 

2^.2 Redeclaration in an Enclosed Block 

Suppose that outer is a block, and inner is another block that is enclosed 
within outer. If an identifier declared in block outer has a further declaration 
in block inner, then block inner and all blocks enclosed by Inner are excluded 
from the scope of the declaration in block outer. (See Appendix B for some 
odd cases.) 

2^.3 Position of Declaration within Its Block 

The declaration of an identifier or label must precede all corresponding 
occurrences of that identifier or label in the program text —i.e., identifiers and 
labels cannot be used until after they are declared. 

There is one exception to this rule: The base- type of a pointer- type (see 
Section 3.3) can be an identifier that has not yet been declared. In this case, 
the identifier must be declared somewhere in the same type-declaration-part 
in which the pointer-type occurs. (See Appendix B for some odd cases.) 

2.2.4 Redeclaration within a Block 

An identifier or label cannot be declared more than once in the outer level of 
a particular block, except for record field identifiers. 

A record field identifier (see Sections 3.2.2, 4.3, and 4.3.2) Is declared within a. 
record-type. It is meaningful only in combination with a reference to a 
variable of that record-type. Therefore a field identifier can be declared 
again within the same block, as long as It Is not declared again at the same 
level within the same record-type. Also, an Identifier that has been declared 
to denote a constant, a type, or a variable can be declared again as a record 
field Identifier In the same block. 



2-3 



Pascal Reference Manual Blocks, Locality, & Scope 

22S Identiflen of Standard Objects 

Pascal on the Lisa provides a set of standard (predeclared) constants^ types, 
procedures, and functions. The identifiers of these objects behave as if they 
were declared in an outermost block enclosing the entire program; thus their 
scope includes the entire program. 
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A type is used in declaring variables; it determines the set of values which 
those variables can assume, and the operations that can be performed upon 
them. A type-declaration associates an identifier with a type. 



type-ciecJaration 



identifier 



O 



type 



O 



tme. 



"T 



simple-type 



structured-type 



pointer- type 



k_ 



The occurrence of an identifier on the left-hand side of a type-declaration 
declares it as a type-identifier for the block in which the type-declaration 
occurs. The scope of a type-identifier does not include its own declaration, 
except for pointer-types (see Sections 2.2.3 and 3.3). 

To help clarify the syntax description with some semantic hints, the following 
terms are used to distinguish identifiers according to what they denote. 
Syntactically, all of them mean simply an identifier: 

simple-type-identifier 

structured- type-i dentif ier 

pointer-type-identifier 

ordlnal-type-ldsntifier 

real-type-identifier 

string-type-identifier 

In other words, a simple-type-identifier is any identifier that is declared to 
denote a simple type, a structured-type-identifier is any identifier that is 
declared to denote a structured type, and so forth. A simple-type-identifier 
can be the predeclared identifier of a standard type such as integer, boolean, 
etc. 
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3.1 Simple-Types (and Ordinal-Types) 

All the simple-types define ordered sets of values. 



simple-type 



ordinal-type 



^^ 



real-type 



^ string-type - 



> 



real type ^ i real-type-identifier 



ordinal-type 



subrange- type 



enumerated- type 



ordinal-type-identifier 



The standard real-type-identifier is reaL 

String-types are discussed in Section 3.1.1.6 below. 

Ordinal -types are a subset of the simple-types, with the following special 
characteristics: 

• Within a given ordinal-type, the possible values are an ordered set and each 
possible value is associated with an ordlnality which is an integer value. 
TX\B first value of the ordinal-type has ordinality 0, the next has ordinality 
1, etc. Each possible value except the first has a predecessor based on 
this ordering, and each possible value except the last has a successor based 
on this ordering. 

• The standard function ord (see Section 11.5.1) can be applied to any value 
of ordinal-type, and returns the ordinality of the value. 

• The standard function pred (see Section 11.5.4) can be applied to any value 
of ordinal-type, and returns the predecessor of the value. (For the first 
value in the ordinal-type^ the result Is unspecified.) 

• The standard function succ (see Section 11.5.3) can be applied to any value 
of ordinal-type, and returns the successor of the value. (For the first value 
in the ordinal-type, the result is unspecified.) 
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All simple- types except real and the string- types are ordinal-types. The 
standard ordinal-type-ldentlfiers are: 

Integer 
longlnt 
char 
boolean 

Note that in addition to these standard types, the enumerated-types and 
subrange-types are ordinal-types. 

3.L1 Standard Simple-Types and String-Types 

A standard type is denoted by a predefined type-identifier. The simple-types 
integer, longlnt, real, char, and boolean are standard. The string-types are 
user-ctefJned simple-types. 

3.L1.1 The Integer Type 

The values are a subset of the whole numbers. (As constants, these values can 
be denoted as specified in Section 1.4.) The predefined integer constant maxint 
is defined to be 32767. Maxint defines the range of the type integer as the 
set of values: 

-maxint-1, -maxint, ... -1, 0, 1, ... maxint- 1, maxint 

These are 16-bit, 2's-complement integers. 

3.1.1.2 The Longint Type 

The values are a subset of the whole numbers. (As constants, these values can 

be denoted as specified in Section 1.4.) The range is the set of values from 

-(2^^-l) to 2^^-l, i.e., -2147483648 to 2147483647. 

These are 32-bit integers. 

Arithmetic on integer and longint operands is done in both 16-blt and 32-bit 
precision. An expression with mixed operand sizes is evaluated in a manner 
similar to the FCRTRAN single/double precision floating-point arithmetic rules: 

• All "integer" constants in the range of type integer are considered to be of 
type integer. All "integer" constants in the range of type longint, but not 
in the range of type integer, are considered to be of type lon^nt 

• When both operands of an operator (or the single operand of a unary 
operator) are of type integer, i6-bit operations are always performed and 
the result is of type integer (truncated to 16 bits if necessary). 

• When one or both operands are of type longint, all operands are first 
converted to type longint, 32-bit operations are performed, and the result is 
of type longint However, if this value is assigned to a variable of type 
integer, it is truncated (see next rule). 
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• The expression on the right of an assignment statement is evaluated 
inctependently of the size of the variable on the left If necessary, the 
result of the expression is truncated or extended to match the size of the 
variable on the left 

The ord4 function (see Section 11.3.3) can be used to convert an Integer value 
to a longlnt value. 

IMPLEMENTATION NOTTE 

There is a performance penalty for the use of longlnt values. The 
penalty is essentially a factor of 2 for operations other than division 
and multiplication; for division and multiplication the penalty is much 
worse than a factor of 2. 



3.L13 The Real Type 

For details of IEEE standard floating-point arithmetic, see Appendix D. The 
possible real values are 

• Finite values (a subset of the mathematical real numben). As constants, 
these values can be denoted as specified in Section 1.4. 

The largest absolute numeric real value is approximately 3.402823a66E38 in 
Pascal notation. 

The smallest absolute numeric non-zero real value is approximately 
1.401298464E-45 in Pascal notation. 

The real zero value has a sign, like other numbers. However, the sign of a 
zero value is disregarded except In division of a finite number by zero and 
in textual output. 

• Infinite values, *^ and -». These arise either as the result of an operation 
that overflows the maximum absolute finite value, or as the result of 
dividing a finite value by zero. Appendix D gives the rules for arithmetic 
operations using these values. 

• NaNs (the word "NaN" stands for "Not a Number"). These are values of 
type real that convey diagnostic information. For example, the result of 
multiplying » by is a NaN. 

3.1.1.4 The Boolean Type 

The values are truth values denoted by the predefined constant identifiers false 
and tiue. These values are ordered so that false is "less than" true. The 
function-call ord(false) returns 0, and ordCtiue) returns 1 (see Section 11.5.1). 

3.1.15 The Char Type 

The values are extended 8-bit ASCII, represented by numeric codes in the 
range 0..255. The ordering of the char values is defined by the ordering of 
these numeric codes. The function-call oid[c)i, where c is a char value, returns 
the numeric code of c (see Section ll.5.1> 
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3.1.1.6 String-Types 

A String value Is a sequence of characters that has a dynamic length attri- 
bute. The length is the actual number of characters in the sequence at any 
time during program execution. 

A string type has a static size attribute. The size is the maximum limit on 
the length of any value of this type. The current value of the length attribute 
is returned by the standard function length (see Section 11.6); the size attribute 
of a string type is determined when the string type is defined. 

stiing-type 

-» ( string ) — »(D— H size-attribute"] — »(T)- 



string-type-identlfler 



I 



sJze-attrJ£K/te 



unsigned-integer 



where the size attribute is an unsigned-integer. 

IMPLEMENTATION NOTE 



In the current Implementation, the size-attribute must be In the range 
from 1 to 255. 



The ordering relationship between any two string values Is determined by 
lexical comparison based on the ordering relationship between character values 
in corresponding positions In the two strings. (When the two strings are of 
unequal lengths, each character In the longer string that does not correspond to 
a character in the shorter one compares "higher"; thus the string 'attribute' Is 
ordered higher than 'at'.) 

Do not confuse the size with the length. 
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NCTTES 

The size attribute of a string constant Is equal to the length of the 
string constant value^ namely the number of characters actually in the 
string. 

Although string-types are simple-types by definition, they have some 
characteristics of structured-types. As explained in Section 4.3.1, 
individual characters In a string can be accessed as If they were 
components of an array. Also, all string-types are implicitly packed 
types and all restrictions on packed types apply to strings (see Sections 
7.3.2, 5.1.6.1, and 11.7). 

Do not make any assumptions about the internal storage format of strings, as 
this format may not be the same in all implementations. 

Operators applicable to strings are specified In Section 5.1.5. Standard 
procedures and functions for manipulating strings are described in Section 11.6. 

3.1.2 Enumerated-Types 

An enumerated- type defines an ordered set of values by listing the identifiers 
that denote these values. The ordering of these values is determined by the 
sequence in which the identifiers are listed. 



enumeratea-type ^ ( jy_^ identifier-n;r|--»(y>-» 



identifier-list 



Identifier 



^ — Q^ 

The occurrence of an identifier within the identifier-list of an 
enumerated-type declares it as a constsait for the block in which the 
enumerated-type is declared. The type of this constant is the enumerated-type 
being declared. 

Examples of enumeratecf-types: 

color = (red^yeiioi»,green^Dlue) 

suit = (club^ diamond, heart, spade) 

marltaistatus = (married, divorced, vldoved, single) 

Given these declarations, yellow is a constant of type color, diamond is a 
constant of type suit, and so forth. 

When the ord function (see Section 11.5.1) is applied to a value of an 
enumerated-type, it returns an integer representing the ordering of the value 
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wltn respect to the otner values of the enumerated- type. For example, given 
the declarations above^ ord(recl) returns 0. ord(yellow) returns l, and ord(blue) 
returns 3. 

3.1.3 Sitorange-Types 

A subrange-type provides for range-checking of values within some 
ordinal-type. The syntax for a subrange-type is 

subranqre-t/pe 



Both constants must be of ordinal-type. Both constants must either be of the 
same ordinal-type, or one must be of type integer and the other of type 
longint If both are of the same ordinal-type, this type is called the host-type 
If one is of type integer and the other of type longint, the host-type is longint 
Note that no range-checking is done if the host-type is longint 

Examples of suDrange-types: 

1..100 
-10.. ♦lO 
red.. green 

A variable of subrange-type possesses all the properties of variables of the 
host type, with the restriction that Its run-time value must be in the specified 
closed interval. 

IMPLEMENTATION NOTE 

Range-Checking is enabled and disabled by the compiler commands $R+ 
and $R- (see Chapter 12). The default is $R+ (range-checking enabled). 



3.2 Structured-Types 

A Structured-type is characterized by its structuring method and by the type(s) 
of its components. If the component type is Itself structured, the resulting 
structured-type exhibits more than one level of structuring. There is no 
specified limit on the number of levels to which data-types can be structured. 
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The use of the word packed in the declaration of a structured-type indicates 
to the compiler that data storage should de economized, even if this causes an 
access to a component of a variable of this type to be less efficient 

The word packed only affects the representation of one level of the 
structured-type in which it occurs. If a component is itself structured, the 
component's representation is packed only if the word packed also occurs in 
the declaration of its type. 

For restrictions on the use of components of packed variaDles, see Sections 
7.3.2, 5.1.6.1, and 11.7. 

The implementation of packing is complex, and details of the allocation of 
storage to components of a packed variable are ^specified 

IMPLEMENTATION NOrTE 

In the current implementation, the word packed has no effect on types 
other than array and record. 

3.2.1 Array-Types 

An array-type consists of a fixed number of components that are all of one 
type, called the component-typa The number of elements is determined by 
one or more index-types, one for each dimension of the array. There is no 
specified limit on the number of dimensions. In each dimension, the array can 
be indexed by every possible value of the corresponding index-type, so the 
number of elements is the product of the cardinalities of all the index-types. 

array-type 



-» (anay} -»([y^^-» [ index-type | -^v-KX)~K^Qr)~ M"^ 



y r\. ) 



O 

index-type 



ordinal-type 



The type following the word of is the component-type of the array. 

IMPLEMENTATION NCTTE 

In the current Implementation, the index-type should not be longint or a 
subrange of longint, and arrays should not contain more than 32767 bytes. 
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Examples of array- types: 

array[l..lOO] of real 
arraytboolean] of color 

If the component-type of an array-type is also an array-type, the result can be 
regarded as a single multi-dimensional array. The declaration of such an array 
is equivalent to the declaration of a multi-dimensional array, as Illustrated by 
the following examples: 

array[t)ool8an] of array[1..10] of array[size] of real 
is equivalent to: 

array [boolean. 1.. 10, size] of real 
Likewise. 

packed array [1.. 10] of packed array[1..8] of boolean 
is equivalent to: 

packed array[l . .10, 1. .8] of boolean 

"Equivalent" means that the compiler does the same thing with the two 
constructions. 

A component of an array can be accessed by referencing the array and 
applying one or more indexes (see Section 4.3.1). 

3.2.2 Record-Types 

A record-type consists of a fixed number of components called flelc/s, possibly 
of different types. For each component, the record-type declaration specifies 
the type of the field and an identifier that denotes it. 



record-type ^ ( ^^^ 



^ field-list — ^ 



->(end 




fixed-part 



I 



field-declaration 



<Z> 



I 
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fleia-declaraUon 



identifier-list — ^\^ — ^ ^MP® 



The fixed-part of a record-type specifies a list of "fixed" fields, giving an 
Identifier and a type for each field. Each of these fields contains data that Is 
always accessed in the same way (see Section 4.3.2). 

Example of a record-type: 

record 
year: integers- 
month: 1..12; 
day: 1..31 

end 

A variant-part allocates memory space with nnore than one list of fields, thus 
permitting the data in this space to be accessed in more than one way. Each 
list of fields is called a variant The variants "overlay" each other in memory, 
and all fields of all variants are accessible at all times. 



varlait-part 



^identifier f H^iY 



tag- field- type 



of 




■> variant -s^^ 



i/ar/ant 



r 



constant 



O 



J 



OQ> 



\r- — J * 

^ field-list -^ 



(Th- 



taQ-fJeld-type ^ 



ordinal-type-identifier 



IMPLEMENTATION NOTE 



In the current implementation, the type longint should not be used as a 
tag-type as it will not work correctly. 
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Each variant is introduced by one or more constants. All the constants must 
be distinct and must be of an ordinal-type that is compatible with the 
tag-type (see Section 3.4). 

The variant-part allows for an optional identifier, called the tag-fleia 
Identifier. If a tag-field identifier is present, it is automatically declared as 
the identifier of an additional fixed field of the record, called the tag-field 

The value of the tag-field may be used by the program to indicate which 
variant should be used at a given time. If there is no tag-field, then the 
program must select a variant on some other criterion. 

Exanrpies of record-types with variants: 

record 
name, flrstName: strlng[80]; 
age: 0..99; 

case married: boolean of 
true: (spousesName: strlng[80]); 
false: 
end 

record 
>cy: real; 
area: real; 
case s: sr^pe of 
triangle: (side: real; Inclination, anglel, angle2: 

angle); 
rectangle: (sidel,. side2 : real; skew, angle3: angle); 
circle: (diameter: real); 
end 

NOTE 

The constants that introduce a variant are not used for referring to 
fields of the variant; however, they can be used as optional arguments 
of the new procedure (see Section 11.2). Variant fields are accessed in 
exactly the same way as fixed fields (see Section 4.3.2). 

3^3 Set-Types 

A set-type defines a range of values that is the powerset of some ordinal-type, 
called the base-type In other words, each possible value of a set-type is some 
subset of the possible values of the base-type. 



^^~^yP^ — »(ser)-»(^or)-» [ ordinal-type 
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IMPLEMENTATION NOTE 

In me present implementation the base-type must not be longint The 
base-type must not have more than 4088 possible values. If the base- 
type is a subrange of integer, it must be within the limits 0..a087. 

Operators applicable to sets are specified in Section 5.1.4. Section 5.3 shows 
how set values are denoted in Pascal. 

Sets with less than 32 possible values in the base-type can be held in a 
register and offer the best performance. For sets larger than this, there is a 
performance penalty that is essentially a linear function of the size of the 
base-type. 

The empty set (see Section 5.1.4) is a possible value of every set-type. 

3.2.4 File-Types 

A file-type is a structured-type consisting of a sequence of components that 
are all of one type, the component-typa The component-type may be any 
type. 

The component data is not in program-addressable memory but is accessed via 
a peripheral device. The number of components (i.e. the length of the file) is 
not fixed by the file-type declaration. 

file-type ^ ( -^ 



^^(^^Ty- ^ type y 



The type file (without the "of type" construct) represents a so-called "untyped 
file" type for use with the blockread and blockwrite functions (see Section 
10.4). 

NOTE 

Although the symbol file can be used as if it were a type-identifier, it 
cannot be redeclared since it is a reserved word. 



The standard file-type text denotes a file of text organized into lines. The 
file may be stored on a file-structured device, or it may be a stream of 
characters from a character deulce such as the Lisa keyboard. Files of type 
text are supported by the specialized I/O procedures discussed in Section 10.3. 

In Pascal on the Lisa, the type text is distinct from the type file of char 
(unlike standard Pascal). The type file of char is a file whose records are of 
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type char, containing char values that are not interpreted or converted in any 
way during I/O operations. 

In a stored file of type text or file of -128..127, the component values are 
packed into bytes on the storage medium. However, this does not apply to the 
type file of char; the component values of this type are stored in 16-Dit words. 

In Pascal on the Lisa, files can be passed to procedures and functions as 
variable parameters, as explained in Section 7.3.2. 

Sections a.3.3, 10.2, 10.3, and 10.4 discuss methods of accessing file components 
and data. 

3.3 Pointer-Types 

A pointer- type defines an unbounded set of values that point to variables of a 
specified type called the base- type 

Pointer values are created by the standard procedure new (see Section 11.2.1), 
by the e operator (see Section 5.1.6), and by the standard procedure pointer 
(see Section 11.3.4). 



fxjlnter-tn:^ 



^ DC 



\_)-^ base- type |- 



polnter-type-identlfier 



T 



base-type 



type-identifier 



NOTE 



The base-type may be an identifier that has not yet been declared. In 
this case, it must be declared somewhere in the same block as the 
pointer-type. 



3.4 



The special symbol nil represents a standard pointer-valued constant that is a 
possible value of every pointer type. Conceptually, nil is a pointer that does 
not point to anything. 

Section 4.3.4 discusses the syntax for referencing the object pointed to by a 
pointer variable. 

Identical and Compatible Types 

As explained below, this Pascal has stronger typing than standard Pascal. In 
Pascal on the Lisa, two types may or may not be identical and identity is 
required in some contexts but not in others. 
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Even if not identical, two types may still be corrpatible, and this is sufficient 
in contexts where identity is not required — except for assignment, where 
assignment-compatibility is required. 

3A1 Type Identity 

Identical types are required only in the following contexts: 

• Variable parameters (see Section 7.3.2). 

• Result types of functional parameters (see Section 7.3.4). 

" Value and variable parameters within parameter-lists of procedural or 
functional parameters (see Section 7.3.5). 

• one-dimensional packed arrays of char being compared via a relational 
operator (see Section 5.1.5). 

Two types, tl and t2, are icfentical if either of the following is true: 

• The same type identifier is used to declare both ll and t2, as in 

foo = "integer; 
tl = foo; 
t2 = foo; 

• tl is declared to be equivalent to t2 as in 

tl = t2; 

Note that the declarations 

tl = t2; 
t3 = tl; 

do not make t3 and t2 identical, even though they make tl identical to t2 and 
t3 identical to tl! 

Also note that the declarations 

t4 = integer; 
t5 = integer; 

do make t4 and 15 identical, since both are defined by the same type 
identifier. In general, the declarations 

t6 = XI; 
t8 = t7; 

do make t6 and t8 identical if t7 is a type-identifier. 

However, the declarations 

t9 = "integer; 
tlO = "integer; 

do not make t9 and tlO identical since "Integer is not a type identifier but a 
user-defined type consisting of the special symbol " and a type identifier. 
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Finally^ note tnai two variaDles declared In tne same declaration, as in 

varl^ var2: "integers- 
are of identical type. However, if the declarations are separate then the 
definitions above apply. 

The declarations 

varl: "integer; 

var2: "Integer; 

var3: integer; 

var4: integer; 

make \/ar3 and var4 identical in type, but not varl and var2. 

3A2 CompaUbllity of Types 

Compatibility is required in the majority of contexts where two or more 
entities are used together, e.g. in expressions. Specific instances where type 
compatibility is required are noted elsewhere in this manual. 

Two types are conpaUble if any of the following are true: 

• They are identical. 

• One is a subrange of the other. 

• Both are subranges of the same type. 

• Both are string- types (the lengths and sizes may differ). 

• Both are set-types, and their base-types are compatible. 

3.4.3 Assignment-Compatibility 

Assignment-compatibility is required whenever a value is assigned to 
something, either explicitly (as In an assignment-statement) or Implicitly (as In 
passing value parameters). 

The value of an expression expval of type exptyp Is assignment-compatible 
with a variable, parameter, or function-identifier of type vtyp If any of the 
following is true. 

• vtyp and exptyp are Identical and neither is a file-type, or a structured- 
type with a file component. 

• vtyp is real and exptyp is Integer or longint (expval Is coerced to type 
real). 

• vtyp and exptyp are compatible ordinal-types, and expval is within the 
range of possible values of vtyp. 

• vtyp and exptyp are compatible set-types, and all the members of expval 
are within the range of possible values of the base-type of vtyp. 

• vtyp and exptyp are string types, and the current length of expval is equal 
to or less than the size-attribute of vtyp. 
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• vlyp is a siring type or a char type and expv/al is a quoted-character- 
constant. 

• vtyp is a packed array(l../7] of char and expval is a string constant 
containing exactly n characters. 

If the index- type of the packed array of char is not \^n. Out the array 
does have exactly n elements, no error will occur. However, the results 
are unspecified. 

Whenever assignment-compatibility is required and none of the above is true, 
either a compiler error or a run-time error occurs. 

3.5 The Type-Declaration-Part 

Any program, procedure, or function that declares types contains a type- 
declaration-part, as shown in Chapter 2. 

Example of a type-declaratJon-part- 

type count = integers- 
range = integers- 
color = (red, yellow, green, blue); 
sex = (male, female); 
year = 1900.. 1999; 
shape = (triangle, rectangle, circle); 
card = array[1..80] of char; 
str = string [80]; 

polar = record r: real; theta: angle end; 
person = "personDetails; 
personDetails = record 

name, firstName: str; 

age: integer; 

married: boolean; 

father, child, sibling: person; 

case s: sex of 
male: (enlisted, bearded: boolean); 
female: (pregnant: boolean) 
end; 

people = file of personDetails; 
intf ile = file of integer; 

In the above example count, range, and Integer denote identical types. The 
type year is compatible with, but not identical to, the types range, count, and 
integer. 
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4.1 Variable-Declarations 

A variable-declaration consists of a list of Identifiers denoting new variables, 
followed by their type. 



varlatJJe-declaraUon 



identifier-lisr"[ -»(7)-» | type | -»(7) ► 



4.2 



The occurrence of an identifier within the identifier-list of a variable- 
declaration declares it as a variable-identifier for the block in which the 
declaration occurs. The variable can then be referenced throughout the 
remaining lexical extent of that block, except as specified in Section 2.2.2. 

Examples of variable-declarations: 

)oy^z: real; 

i,j: integer; 

k: 0..9; 

p,q,r: boolean; 

operator: (plus, minus, times); 

a: array[0..63] of real; 

c: color; 

f : file of char; 

huel,hue2: set of color; 

pl,p2: person; 

ntral,iiC: array [1.. 10,1.. 10] of real; 

coord: polar; 

pooltape: array[1..4] of tape; 

Variable-References 

A variable-reference denotes the value of a variable of simple-type or 
pointer-type, or the collection of values represented x^i^^ a variable of 
structured-type. 



i/arlable-reference 

► 



variable-Identifier - 



n 



qualifier 



^ 



varlable-ldentjfier 



identifier 
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Syntax for the various klnas of qualifiers is given oelow. 

4.3 Quallfien 

As shown above, a variable-reference is a variable-identifier followed by zero 
or more qualifiers Each qualifier modifies the meaning of the variable- 
reference. 



(fjallfier 



"T 



^ 



index 



field-designator 



"^ 



file-buffer-symbol 



^ 



♦- pointer-object-symbol 



V. 



An array identifier with no qualifier is a reference to the entire array: 

xResults 

If the array identifier is followed by an index, this denotes a specific 
component of the array: 

xResults [ current+1 ] 

If the array component is a record, the index may be followed by a field- 
designator; in this case the variable-reference denotes a specific field within a 
specific array component. 

XResults [ current +1 ] . link 

If the field is a pointer, the field-designator may be followed by the pointer- 
object-symbol, to denote the object pointed to by the pointer: 

xResults[current+l] .link " 

If the object of the pointer is an array, another index can be added to denote 
a component of this array (and so forth> 

xResuits[current+i ] . link " [ 1 ] 

4.3.1 Anays, Strings, and Indexes 

A specific component of an array variable is denoted by a variable- reference 
that refers to the array variable, followed by an index that specifies the 
component. 

A specific character within a string variable is denoted by a variable-reference 
that refers to the string variable, followed by an index that specifies the 
character position. 



index 



<t> 



r 



expression 



T 



<i>-^ 
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Examples of indexed arrays: 

a[l*J] 

Each expression in the index selects a component in the corresponding 
dimension of the array. The number of expressions must not exceed the 
number of index-types in the array declaration, and the type of each 
expression must be assignment-compatible with the corresponding index-type. 

In indexing a multi-dimensional array, you can use either multiple indexes or 
multiple expressions within an index. The two forms are completely equivalent. 
For example, 

in[l][j] 

is equivalent to 
n«[i.j] 

For array variables, each index expression must be assignment-compatible with 
the corresponding index-type specified in the declaration of the array-type. 

A string value can be indexed by only one index expression, whose value must 
be in the range 1../7, where n is the current length of the string value. The 
effect is to access one character of the string value. 

WARNING 

When a string value is manipulated by assigning values to individual 
character positions, the dynamic length of the string is not maintained. 
For example, suppose that stival is declared as follows: 

strval: string [10]; 

The memory space allocated for strval includes space for 10 char values 
and a number that will represent the current length of the string—i.e., 
the number of char values currently in the string. Initially, all of this 
space contains unspecified values. The assignment 

strval[l]:=*F* 

may or may not work, depending on what the unspecified length happens 
to be. If this assignment works, it stores the char value T' in character 
position 1, but the length of stival remains unspecified. In other words, 
the value of stival[l] is now T', but the value of strval is unspecified. 
Therefore, the effect of a statement such as writeln(strval) is 
unspecified. 

Therefore, this kind of string manipulation is not recommended, instead, 
use the standard procedures described in Section 11.6. These procedures 
properly maintain the lengths of the string values they modify. 
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4w3.2 Records and Field-Designators 

A specific field of a record variable is denoted by a variable-reference that 
refers to the record variable^ followed by a field-designator that specifies the 
field. 



flelcf-cfeslgnator 



O 



Identifier 



Examples of fleia-designaton: 

p2". pregnant 
(xwrd.theta 

4.3.3 Flle-Buffen 

Although a file variable may have any number of components, only one 
component is accessible at any time. The position of the current component in 
the file is called the current file position See Sections 10.2 and 10.3 for 
standard procedures that move the current file position. Program access to the 
current component is via a special variable associated with the file, called a 
flle-Ouffen 

The file-buffer is implicitly declared when the file variable is declared. If F 
is a file variable with components of type T, the associated file-buffer is a 
variable of type T. 

The file-buffer associated with a file variable is denoted by a variable- 
reference that refers to the file variable, followed by a qualifier called the 
file-buffer-symbol. 



file-lMffer-symixtl 



O 



Thus the file-buffer of file F is referenced by F . 

Sections 10.2 and 10.3 describe standard procedures that are used to move the 
current file position within the file and to transfer data between the file- 
buffer and the current file component. 

4.3.4 Pointers and Their Objects 

The value of a pointer variable is either nil, or a value that identifies some 
other variable, called the otyject of the pointer 

The object pointed to by a pointer variable is denoted by a variable-reference 
that refers to the pointer variable^ followed by a qualifier called the pointer- 
object-symbol. 



polnter-otJiect-symbol 



O 
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NOTE 

Pointer values are created by the standard procedure new (see Section 
11.2.1), by the » operator (see Section 5.1.6), and by the standard 
procedure pointer (see Section 11.3.4). 

The constant nil (see section 3.3) does not point to a variable. If you access 
memory via a nil pointer reference, the results are unspecified; there may not 
be any error Indication. 

Exanfiples of references to obpcts of pointers: 

pi: 

pi .sibling 
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Expressions consist of operators and operands, i.e. variables, constants, set- 
constructon, and function calls. Table 5-1 shows the operator precedence: 

Table 5-1 
Precedence of Gperaton 



Cperators 


« 


Categories 


PfBcedence 


«, not 


highest 


unary operaton 


*, /, div, 
mod, and 


second 


"multiplying" operators 


♦, -, or 


third 


"adding" operators & signs 


<-, >=, in 


lowest 


relational operators 



The following rules specify the way in which operands are bound to operators: 

• When an operand is written between two operators of different precedence, 
it is bound to the operator with the higher precedence. 

• When an operand is written between two operators of the same precedence, 
it is bound to the operator on the left 

Note that the order in which operations are performed is not specified. 

These rules are implicit in the syntax for expressions, which are built up from 
factors, terms, and simple-expressions. 

The syntax for a /Sctor allows the unary operators » and not to be applied to 
a value: 



factor 








\ 




N 






V^ 














^ 












'" ■ ^ Tunc Lion Call 


> 














■ ^ 






""^ Kj)~^ expression ^(7) 






^ ^f rv^tV...^ f-^Atrir 


^ te 
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A function-call activates a function, and denotes tne value returned Dy the 
function (see Section 5.2). A set-constructor t^v^X^i a value of a set-type (see 
Section 5.3). An msigieo-constait has the following syntax: 



unsipneO-constant 



^ 



^ 



»^ 



unsigned-number 



quoted-string-constant 



"^ 



constant-identifier 



> 



"K^ 



L. 



Examples of factors: 

X 

ax 

15 

(x*y*z) 

sin(x/2) 

[•A'..'F'.'a'..-f ] 

not p 

The syntax for a term allows the "multiplying" operators to be applied to 
factors: 



{variable-reference} 
{pointer to a variaDle} 
{unsigned-constant > 
{sub-expression} 
{function-call} 
{set-constructor} 
{negation of a boolean} 




Examples of terms: 

x*7 

1/(1-1) 
p and q 
(X <= y) and (y < z) 
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The syntax for a simple-expression allows the "adding" operators and signs to 
be applied to terms: 



simple-expression 



^ sian -^ 






term 



^ 






Examples of sinple-expressims: 

x+y 

-X 

huel + hue2 

i*j ♦ 1 

The syntax for an expression allows the relational operators to be applied to 
simple-expressions: 

expression 



simple-expression 






simple-expression 



Exanrples of expressions: 

X = 1.5 

p <= q 

p = q and r 

(i < J) = (J < k) 
c in huel 
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5.1 Gperaton 
5.1.1 Binary Operators: Order of Evaluation of Operands 

The order of evaluation of the operands of a binary operator is unspecified. 

5.L2 Arithmetic Operators 

The types of operands and results for arithmetic binary and unary operations 
are shown in Tables 5-2 and 5-3 respectively. 

Table 5-2 
Binary Arithmetic Operations 



Cperator 


CperaUon 


Cperand Types 


Type of Result 


•*■ 


addiUon 


integer, real, or 
Icngint 


integer, real, or 
longint 


- 


SLtotraction 


» 


multiplication 


/ 


division 


integer, real, or 
longint 


real 


div 


division with 
integer result 


intfiger or longint 


integer or longint 


mod 


modulo 


integer or longint 


integer 


Note: The symbols ♦, -^ and « are also used as set operators (see 
SecUon 5.1.4). 



Table 5-3 
unary Arithmetic Operations (Signs) 



Cperator 


operation 


operana Types 


Type of Result 


*■ 


identity 


integer, real, or 
lon^t 


same as operand 


- 


sign-negation 



Any operand whose type is subr, where subr is a subrange of some ordinal-type 
ordtyp, is treated as if It were of type oidtyp. Consequently an expression 
that consists of a single operand of type subr is itself of type ordtyp. 
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If both the operands of the addition, subtraction, or multiplication operators 
are of type integer or longint, the result is of type integer or longint as 
described in Section 3.1.1.2; otherwise, the result is of type real 

NOTE 

See Appendix D for more information on all arithmetic operations with 
operands or results of type real 

The result of the identity or sign-negation operator is of the same type as the 
operand. 

The value of i div j is the mathematical quotient of i/J, rounded toward zero 
to an integer or longint value. An error occurs If >-0. 

The value of i mod j is equal to the value of 

i - (i dlv j)»j 

The sign of the result of mod Is always the same as the sign of 1. An error 
occun If j-0. 

The predefined constant maxint is of type integer. Its value Is 32767. This 
value satisfies the following conditions: 

• All whole numbers in the closed interval from -maxint-1 to +maxlnt are 
representable in the type integer. 

• Any unary operation performed on a whole number in this interval will be 
correctly performed according to the mathematical rules for whole-number 
arithmetic. 

• Any binary Integer operation on two whole numbers In this same Interval 
will be correctly performed according to the mathematical rules for 
whole-number arithmetic, provided that the result is also In this Interval. 
If the mathematical result is not in this interval, then the actual result Is 
the low-order 16 bits of the mathematical result 

• Any relational operation on two whole numbers In this same Interval will be 
correctly performed according to the mathematical rules for whole-number 
arithmetic. 



5-5 



Pascal Reference Manual 



Expressions 



5.13 Boolean Qperaton 

The types of operands and results for Boolean operations are shown in Table 
5-4. 



Table 5-4 
Boolean Operations 



cperator 


Operation 


cperana Types 


Type of Result 


or 


disjunction 


ixx)lean 


boolean 


and 


conjunction 


not 


negation 



Whether a Boolean expression is completely or partially evaluated if its value 
can be determined by partial evaluation is unspecified. For example, consider 
the e>qDression 

true or txx)lTst(x) 

where txwlTst Is a function that returns a txwlean value. This expression will 
always have the value true, regardless of the result of boolTst(x). The language 
definition does not specify whether the boolTst function Is called when this 
expression Is evaluated. This could be Important If boolTst has side-effects. 

5.L4 Set Qperaton 

The types of operands and results for set operations are shown in Table 5-5. 



Table 5-5 
Set Operations 



Operator 


operation 


Operand Types 


Type of Result 


♦ 


union 


compatible 
set-types 


(see 5.1.4.1) 


- 


difference 


» 


intersection 
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5.1A1 Result Type in Set Operations 

The following ailes govern the type of the result of a set operation where one 
(or both) of the operands is a set of subr, where ordtyp represents any 
ordinal- type and subr represents a subrange of ordtyp: 

• If ordtyp is not the type Integer, then the type of the result is set of 
ordtyp. 

• If ordtyp is the type integer, then the type of the result is set of 0.4087 in 
the current implementation (0..32767 in a future implementation). This rule 
results from the limitations on set-types (see Section 3.2.5). 

5.1.5 Relational Operators 

The types of operands and results for relational operations are shown in Table 
5-6, and discussed further below. 

Tables^ 
Relational Operations 



Qoerator 


Operation 


OperarKi Types 


Type of Result 


- 


equal 


compatible set-, 
simple-, or 
pointer-types 
(& see below) 


boolean 


<> 


not equal 


< 


less 


compatible 
simple-types 
(& see below) 


> 


greater 


<- 


less/equal 


>- 


greater/eqi«] 


<= 


subset of 


compatible 
set-types 


>- 


superset of 


in 


member of 


left operand: 
arij/ ordinal-type T 
'Hgfiropers^ 
set of T 



5.1.5.1 Comparing Numben 

When the operands of <, >, >-, or <- are numeric, they need not be of 
conopatible type If one operand is real and the other Is integer or longlnt 

NOTE 

See Appendix D for more information on relational operations with 
operands of type real 
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S.13.2 Comparing Booleans 

If p and q are boolean operands^ then p-q denotes their equivalence and p<-q 
denotes the implication of q by p (because false<triie). Similarly, p<>q denotes 
logical "exclusive-or." 

5.1.53 Comparing Strings 

When the relational operators -,<>,<,>,<-, and > are used to compare 
strings (see Section 3.1.1.6X they denote lexicographic ordering according to the 
ordering of the ASCII character set. Note that any two string values can be 
compared since all string values are compatible. 

5.1.5.4 Comparing Sets 

If u and V are set operands, then u<-v denotes the inclusion of u in v, and 
u>=v denotes the inclusion of v in a 

5.13.5 Testing Set Membership 

The in operator yields the value true if the value of the ordinal-type operand 
is a member of the set-type operand; otherwise it yields the value false. 

5.1.5.6 Comparing Packed Arrays of Char 

In addition to the operand types shown in the table, the - and <> operators can 
also be used to compare a packed arrayCUsQ of char with a string constant 
containing exactly N characters, or to compare two one-dimensional packed 
arrays of char of identicaJ type. 

5.1.6 •-Operator 

A pointer to a variable can be computed with the ©-operator. The operand 
and result types are shown in Table 5-7. 



TaDle 5-7 
Pointer Operation 



Operator 


Cperation 


Operand 


Type of Result 


m 


pointer 
formation 


variable, parameter, 
procedure, or 
function 


same as nil 



» is a unary operator taking a single variable, parameter, procedure, or 
function as its operand and computing the value of its pointer. The type of 
the value is equivalent to the type of nil, and consequently can be assigned to 
any pointer variable. 
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5.1.6.1 ©-Operator With a Variable 

For an ordinary variable (not a parameter), the use of » Is straightforward. For 
example, if we have the declarations 

type twochar = packed array[0..1] of char; 
var int: integer; 

tiwcharptr: "tipochar; 

then the statement 

twocharptr := aint 

causes twocharptr to point to int Now twochaiptr" is a reinterpretation of 
the bit value of int as though it were a packed arTay(a.l] of char. 

The operand of » cannot be a component of a packed variable. 

5.1.6.2 ©-Operator With a Value Parameter 

When • is applied to a formal value parameter, the result is a pointer to the 
stack location containing the actual value. Suppose that foo is a fornnal value 
parameter in a procedure and fooptr is a pointer variable. If the procedure 
executes the statement 

fooptr := «foo 

then fooptr* is a reference to the value of foa Note that if the actual- 
parameter is a variable-reference, fooptr" is not a reference to the variable 
itself; it is a reference to the value taken from the variable and stored on the 
stack. 

5.1.6.3 9-Operator With a variable Parameter 

When e is applied to a formal variable parameter, the result is a pointer to 
the actual-parameter (the pointer is taken from the stack). Suppose that fum 
is a formal variable parameter of a procedure, fie is a variable passed to the 
procedure as the actual-parameter for fln^, and fumptr is a pointer variable. 

If the procedure executes the statement 

furaptr := afum 

then fumptr is a pointer to fia ftinptr" is a reference to fie itself. 

5.1.6.4 ©-Operator With a Procedure or Function 

It is possible to apply • to a procedure or a function, yielding a pointer to the 
entry-point Note that Pascal provides no mechanism for using such a pointer. 
Currently the only use for a procedure pointer is to pass it to an assembly- 
language routine, which can then JSR to that address. 

If the procedure pointed to is in the local segment, » returns the current 
address of the procedure's entry point If the procedure is in some other 
segment^ however, e returns the address of the jump table entry for the 
procedure. 
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In logical memory mapping (see Workshop User's Guide for the Lisa), the 
procedure pointer is always valid. 

In physical memory mapping, code swapping may change a local-segment 
procedure address without warning, and the procedure pointer can become 
invalid. If the procedure is not in the local segment, the jump-table entry 
address will remain valid despite swapping because the jump table is not 
moved. 

5.2 Function-Calls 

A function-call specifies the activation of the function denoted by the 
function-identifier. If the corresponding function-declaration contains a list of 
formal-parameters, then the function-call must contain a corresponding list of 
actual-parameters. Each actual-parameter is substituted for the corresponding 
formal-parameter. The correspondence is established by the positions of the 
parameters in the lists of actual and formal parameters respectively. The 
number of actual-parameters must be equal to the number of formal 
parameters. 

The order of evaluation and binding of the actual-paranneters is unspecified. 



functlon-call 

^ 



function-identifier 



"^ 



actual-paraneter-list 



vr 



actual-paraimter-m »(7>-^-» |l^tual-parameter | -^-»()> 



u 



o 



actual -parameter 



-v-^ 



'"--i^ variable-reference 



expression 



procedure-identifier 



function-identifier 



-> 



k. 



A function-identifier is any identifier that has been declared to denote a 
function. 
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Examples of function-calls: 

suin(^63) 

gcd(147,k) 

sin(x+y) 

eof(f) 

ord(f'') 

5.3 Set-Constiuctors 

A set-constructor denotes a value of a set-type, and is formed by writing 
expressions within [brackets]. Each expression denotes a value of the set 

set-constructor ^(Y\ ^^JW 

V — _ , fc momhoT— firm in — -^ 



member-group 



C— ^ iiiBinuei-yiuup — ^- 
— o- — ^ 



nientfer-aixK4} 



expression 



^-»(V)— » expression -^ 



The notation [ ] denotes the empty set, which belongs to every set-type. Any 
member-group x..y denotes as set members the range of all values of the base- 
type In the closed interval x to y. 

If X is greater than y, then x..y denotes no members and [x..y] denotes the 
empty set 

All values designated in member-groups in a particular set-constructor must be 
of the same ordinal-type. This ordinal-type is the base-type of the resulting 
set If an Integer value designated as a set member is outside the limits given 
in section 5.2.3 (o..aD87 in the current implementation), the results are 
unspecified. 

Examples of set-constnxitors: 

[red, c, green] 

[1. 5, 10.. k mod 12, 23] 

['A'..'z*, 'a'..'z', chr(xcode)] 
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statements 



statements denote algorithmic actions, and are executable. They can de 
prefixed by labels; a labeled statement can be referenced by a goto-statement. 



statenwnt 



^ label -^Qy^ ^ simple-statement -j^ 



^ structured-statement 



JabeJ 



digit-sequence 



A digit-sequence used as a label must be in the range 0..9999, and must first 
be declared as described in Section 2.1. 

6.1 Simple Statements 

A simple-Statement is a statement tMat does not contain any other statement. 



sJmpJe-statement 



T 



assignment-statement 



procedure-statement 



■^ 



goto-statement 



L- 



6.1.1 Assignment-Statements 

The syntax for an assignment-statement is as follows: 



assjgviient-$t3tenimt 



T] 



variable-reference 



function-identifier 



^CE) — ^ expression 



The assignment-statement can be used in two ways: 

• To replace the current value of a variable by a new value specified as an 
expression 

• To specify an expression whose value is to be returned by a function. 
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The expression must be assignnnenl-compatible with the type of the variable or 
the result-type of the function. 

NOfTE 

If the selection of the variable involves indexing an array or taking the 
object of a pointer, it is not specified whether these actions precede or 
follow the evaluation of the expression. 



Exwrples of asslg^rr^nt-staterr^nts: 

X := y+z; 

p := (l<=i) and (i<100); 
i := sqr(k) - (l*j); 
huel := [blue,succ(c)]; 

6.L2 Procedure-Statements 

A procedure-statement serves to execute the procedure denoted by the 
procedure-identifier. 

prcceckjre-st3tenient 

► 



procedure-identifier 



t;^ 



actual-parameter-list 



(A procedure-identifier is simply an identifier that has been used to declare a 
procedure.) 

If the procedure has formal-parameters (see Section 7.3), the procedure- 
statement must contain a list of actual-parameters that are bound to the 
corresponding formal-parameters. The number of actual-parameters must be 
equal to the number of formal parameters. The correspondence is established 
by the positions of the parameters in the lists of actual and formal parameters 
respectively. 

The rules for an actual-parameter AP depend on the corresponding formal- 
parameter FP: 

• If FP is a value parameter, AP must be an expression. The type of the 
value of AP must be assignment-compatible with the type- of PP. 

• If FP is a variable parameter, AP must be a variable-reference. The type 
of AP must be identical to the type of FP. 

• If FP is a procedural parameter, AP must be a procedure-identifier. The 
type of each formal-parameter of AP must be identical to the type of the 
corresponding formal-parameter of FP. 



6-2 



Pascal Reference Manual Statements 



• If FP is a functional parameter, AP must be a function-identifier. The type 
of each formal-parameter of AP must be identical to the type of the 
corresponding formal-parameter of FP, and the result- type of AP must be 
identical to the result-type of FP. 

hJOTE 

The order of evaluation and binding of the actual parameters is 
unspecified. 



ExanpJes of pwceck/re-statenwnts: 

prlntheading; 
transpose(a, a m); 
Dlsect(f ct, -1 . 0, +1 . 0, x); 

6.1.3 Goto-Stalements 

A goto-statement causes a jump to another statement in the program, namely 
the statement prefixed by the label that is referenced in the goto-statement 



QOUi-statenTent » C J^^^)_»p;^ 



NOTE 



The constants that introduce cases within a case- statement (see Section 
6.2.2.2) are not labels, and cannot be referenced in goto-statements. 



The following restrictions apply to goto-statements: 

• The effect of a jump into a structured statement from outside of the 
structured statement is unspecified. 

• The effect of a jump between the tfien part and the else part of an If- 
statement is unspecified. 

• The effect of a jump between two different cases within a case-statement 
is unspecified. 
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bJZ Stmctured-Statenients 

Structured-statements are constructs composed of other statements that must 
be executed either conditionally (conditional-statements), repeatedly 
(repetitive-statements), or in sequence (compound-statement or with-statement). 



structured-statement 



~\ 



compound-statement 



condi tional -statement 



"•^ repetitive-statement 



^ witn-statement 



6-2.1 Compound-Statements 

The compound-statement specifies that its component statements are to be 
executed in the same sequence as they are written. 



compound-statement 



I 



-O 



J 



-»{ ^end) - 



Example of compound-statement- 

begin 

z := x; 

X := y; 

y := z 
end 

An important use of the compound-statement is to group more thsai one 
statement into a single statement, in contexts where Pascal syntax only allows 
one statement The symbols begin and end act as "statement brackets." 
Examples of this will be seen in Section 6.2.3.2. 

6.2.2 Conditional-Statements 

A conditional-Statement selects for execution a single one (or none) of its 
component statements. 



corkJJtlaial-stat^ji&it 



u 



if-statement 



case-statement 
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6.2.2.1 If-Statements 

The syntax for if-statements is as follows: 



if-statement 



<E^ 



expression 




D 



then 



statement 



else 



statement 



TI 



The expression must yield a result of type boolean. If the expression yields 
the value true, the statement following the then is executed. 

If the expression yields false and the else part is present, the statement 
following the else is executed; if the else part is not present, nothing is 
executed. 

The syntactic ambiguity arising from the construct- 

If 81 then 
if 62 then si 
else s2 

is resolved by interpreting the construct as being equivalent to: 

if el then begin 
if 62 then si 
else s2 
end 

Ex&rples of if-statements: 

if X < 1.5 then z := x*y else z := 1.5; 
if pi o nil then pi := pi ".father; 

6.2.2.2 Case-statements 

The case-statement contains an expression (the selectoli and a list of 
statements. Each statement must be prefixed with one or more constants 
(called case-constant^, or with the reserved word otherwise. All the case- 
constants must be distinct and must be of an ordinal-type that is compatible 
with the type of the selector. 



case-statenwnt 



(case)-^ expression 




-*®^ 



otherwise-clause 



►@)-*' 
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case 



r 



constant 



O 



J 



<nH 



statement 



ot/rerwjse-cl^jse 



>(7)— »( ^t/iervise ^ -^ statement 



The case-statement specifies execution of the statement prefixed by a case- 
constant equal to the current value of the selector. If no such case-constant 
exists and an otherwise part is present, the statement following the word 
otherwise is executed; if no otherwise part is present, nothing is executed. 

Examples of case-statements: 



case operator 


Of 


plus: X := 


x+y; 


minus: x := 


x-y; 


times: X := 


x*y 


end 




case 1 of 




1: X 


:= sln(x); 


2: X 


:= cos(x); 


3.4,5: X 


:= exp(x); 


Otherwise x 


:= ln(x) 


end 





IMPLEMENTATION NOTE 



In the current implementation, the case-statement will not work 
conectly if any case-constant is of type longint or the value of the 
selector is of type longint 



6.2.3 Repetitive-Statements 

Repetitive-statements specify that certain statements are to t)e executed 
repeatedly. 



repetJtJt/e-statement 



^ 



repeat-statement 



while-statement 



^ 



^ for-statement 



i- 
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6^-3.1 Repeat-Statements 

A repeat-Statement contains an expression which controls the repeated 
execution of a sequence of statements contained within the repeat-statement 



r^:^at-st3tement 



►{^repeat 



j-f^ statement — r — H 

^ — O—^ 



(until) — ► expression 



The expression must yield a result of type txx)leaa The statements between 
the symbols repeat and until are repeatedly executed until the expression 
yields the value tiue on completion of the sequence of statements. The 
sequence of statements is executed at least once, because the expression is 
evaluated after execution of the sequence. 

ExampJes of re^at-stat&n&itsr 



repeat 



= 1 mod 

= J; 
= k 



until j = 

repeat 

process(f * 

get(f) 
until eof(f) 



); 



6^.3.2 While-Statements 

A while-statement contains an expression which controls the repeated 
execution of one statement (possibly a compound-statement) contained within 
the while-statement. 



wtiile-statement 

►(^ while) — ► expression 



statement 



The expression must yield a result of type boolean. It Is evaluated Ixfore 
contained statement is executed. The contained statement is repeatedly 
executed as long as the expression yields the value tiue. If the expression 
yields false at the beginning, the statement is not executed. 



the 
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The while-statement: 
while t) do body 

is equivalent to: 

if b then repeat 

body 
until not b 

Examples of while-statements: 

while a[i] <> x do i := i+1 

•hile i>0 do begin 

if odd(i) then z := z*x; 

i := i div 2; 

X := sqr(x) 
end 

•hile not eof (f ) do begin 

process(f " ); 

get(f) 
end 

&2.3.3 For-Statements 

The for-statement causes one contained statement (possibly a compound- 
statement) to be repeatedly executed while a progression of values is assigned 
to a variable called the contwl-variatJla 



foi-st3tement 
►TfoT)— ^ control-variable ->(^\-^ initial-value 



C 



D 




®- 



downto 



final-value -»(do)-» statement 



control-variable 



variable-identifier 



initial-value 



expression 



final-value 



«► expression ► 
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The control-v/arladle must be a variable-identifier (without any qualifier). It 
must be local to the Innermost block containing the for-statement, and must 
not be a variable parameter of that block. The control-variable must be of 
ordinal-type, and the Initial and final values must be of a type compatible with 
this type. 

The first value assigned to the control-variable is the initial-value. 

If the for-statement is constructed with the reserved word to, each successive 
value of the control-variable is the successor (see Section 3.1) of the previous 
value, using the inherent ordering of values according to the type of the 
control-variable. When each value is assigned to the control-variable, it is 
compared to the final-value; if it is less than or equal to the final value, the 
contained statement is then executed. 

If the for-statement is constructed with the reserved word downto, each 
successive value of the control-variable is the predecessor (see section 3.1) of 
the previous value. When each value is assigned to the control-variable, it is 
compared to the final-value; if It Is greater than or equal to the final value, 
the contained statement is then executed. 

If the value of the control-variable is altered by execution of the repeated 
statement, the effect is unspecified. After a for-statement is executed, the 
value of the control-variable is unspecified, unless the for-statement was 
exited by a goto. Apart from these restrictions, the for-statement: 

for V := el to e2 do body 

is equivalent to: 

begin 
tempi := el; 
t8fflp2 := e2; 

if teinpl <= tenp2 then begin 
V := tenpl; 
body; 

while V o t8n|)2 do begin 
V := succ(v); 
body 
end 
end 
end 
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and the for-statement: 

for V := el do«»nto e2 do txxly 

Is equivalent to: 

begin 
teinpl := el; 
tenpZ := e2; 

if tenpl >= tewp2 then begin 
V := tenpl; 
body; 

while V <> tenp2 do begin 
V := pred(v); 
body 
end 
end 
end 

where tempi and temp2 are auxiliary variables of the host type of the variable 
V that do not occur elsewhere In the program. 

Ex&npJes of for-statements: 

for i := 2 to 63 do if a[i] > max then max := a[i] 

for i := 1 to n do for j := 1 to n do 
begin 
X := 0; 

for k := 1 to n do X := X + ffll[i,k]*iiC[k, j]; 
m[i.j] := X 
end 

for c := red to blue do q(c) 

6.2.4 With-Statements 

The syntax for a with-statement is 

u^Jth-statement 

— »( ^wlthV r^ record-variable-reference v »(S)-» 



^ 



O 



T 



statement 



(A record-variable-reference is simply a reference to some record variable.) 
The occurrence of a record-variable-reference in a with-statement affects the 
way the compiler processes variable-references within the statement following 
the word da Fields of the record-variable can be referenced by their field- 
identifiers, without explicit reference to the record-variable. 
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ExampJe of wlth-statement- 

•1th date do if month = 12 then begin 

month := 1; 

year := year ♦ 1 
end 
else month := month + 1 

This is equivalent to: 

if date. month = 12 then begin 

date. month := l; 

date.year := date. year + l 
end 
else date. month := date. month * 1 

Within a with-slatement, each variable-reference is checked to see if it can 
be interpreted as a field of the record. Suppose that we have the following 
declarations: 

type recTyp = record 

foo: integers- 
bar: real 
end; 

var baz: recTyp; 
foo: integer; 

The identifier foo can refer both to a field of the record variable baz and to a 
variable of type integer. Now consider the statement 

with baz do begin 
foo := 36; {•hich foo is this?} 

end 

The foo in this with-statement is a reference to the field baz-foo^ not the 
variable foa 

The statement: 

with vl,v2, ... vn do s 

is equivalent to the following "nested" with-statements: 

with VI do 
with v2 do 

with vn do s 
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If vn in the above statements is a field of botn vl and v/2, it is interpreted to 
mean v2.vn, not vl.va The list of record-variable-references in the with- 
statement is checked from right to left 

If the selection of a variable in the record-variable-list involves the indexing 
of an array or the de-referencing of a pointer, these actions are executed 
before the component statement is executed. 

WARNING 

If a variable in the record-variable-list is a pointer- reference, the value 
of the pointer must not be altered within the with-statement. If the 
value of the pointer is altered, the results are unspecified. 

ExampJe of unsafe with-statement using pointer-reference: 

with ppp" do begin 

newCppp); {Don't do this ...} 

ppp:=xxx; {... or this} 

end 
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7.1 ProcedureHDeclarations 

A procedure-declaration associates an identifier with part of a program so that 
it can be activated by a procedure-statement. 

proceaure-declaratlon 

procedure-heading -^T^ procedure-body -^V) — •► 



procedure-tXMiy 



^ 



block 



-»( ^ forward 
-» (exterr^] ) 



ib^ 



The procedure-heading specifies the identifier for the procedure, and the 
formal parameters (if any> 



pivceitJie-heatUrg 

► ( procedure ) — ► identifier 



^ 



formal-parameter-list 



IT 



The syntax for a formal-parameter-list is given in Section 7.3. 

A procedure is activated by a procedure-statement (see Section 6.1.2), which 
gives the procedure's identifier and any actual-parameters required by the 
procedure. The statements to be executed upon activation of the procedure 
are specified by the statement-part of the procedure's block. If the 
procedure's identifier is used in a procedure-statement within the procedure's 
block, the procedure is executed recursively. 
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Exampje of a pwceduw-declaration: 

procedure readlnteger (var f : text; var x: integer); 
var value, dlgitValue: integer; 
begin 
while (f " = • •) and not eof(f) do get(f); 
value := 0; 

while (f" in ['C./g']) and not eof(f) do begin 
digitvalue := ord(f ) - ord('O'); 
value := 10*value ♦ digitValue; 
get(f) 
end; 

X := value 
end; 

A procedure-declaration that has forward instead of a block is called a 
forwarti declaraUon Somewhere after the forward declaration (and in the 
same block), the procedure is actually defined by a defining declaration-di 
procedure-declaration that uses the same procedure-identifier, omits the 
formal-parameter-list, and includes a block. The forward declaration and the 
defining declaration must be local to the same block, but need not be 
contiguous; that is, other procedures or functions can be declared between 
them and can call the procedure that has been declared forward. This permits 
mutual recursion. 

The forward declaration and the defining declaration constitute a complete 
declaration of the procedure. The procedure is considered to be declared at 
the place of the forward declaration. 

Example of forward declaraUon: 

procedure waiter (nun: integer); {fori»ard declaration} 
forward; 

procedure clara(x, y: real); 
begin 

walter(4, 5); {OK because waiter is forward declared} 



end; 

procedure waiter; {defining declaration} 
begin 

ciara(8.3, 2.4); 

end; 

A procedure-declaration that has external instead of a block defines the Pascal 
interface to a separately assembled or compiled routine (a PROC in the case 
of assembly language^ The external code must be linked with the compiled 
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Pascal host program before execution; see the Workshop User's Guide for the 
Lisa for details. 

Example of an external procedure-declaration: 

procedure makescreen( index: integer); 
extemal; 

This means that makescieen is an external procedure that will be linked to the 
host program before execution. 

IMPLEMENTATION NOTE 

It is the programmer's responsibility to ensure that the external 
procedure is compatible with the external declaration in the Pascal 
program; the current linker does no checking. 



NOTE 

This Pascal (unlike Apple II and Apple III Pascal) does not allow a 
variable parameter of an external procedure or function to be declared 
without a type. To obtain a similar effect, use a formal-parameter of 
pointer-type, as in the following example: 

type bigpaoc = packed ar ray [0.. 32767] of char; 
blgpaocptr = '^ bigpaoc; 

procedure Dhatever (bytearray: bigpaocptr); 
external; 

The actual-parameter can be any pointer value obtained via the »- 
operator (see Section 5.1.6). For example, if dots Is a packed array of 
boolean, it can be passed to whatever by writing 
iihatever(adots) 



This description of external procedures also applies to external functions. 
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12 Function-Declarations 

A function-declaration serves to define a part of the program that computes 
and returns a value of simple-type or pointer-type. 

function-declaration 

function-heading -^\T)^ function-body -*\7) — ^ 



function-Cody 



"1 



^ 



hlock 



►{^ forward 
» ( ext.eYT\al }- 



The function-heading specifies the identifier for the functioa the formal 
parameters (if any), and the type of the function result 



function-tieadinq » ( ^]^;^5^^;) > |-5^;;n?i^ 



c 



D 



T] 



formal-parameter-list 



7'~^(Z)~~^ result-type 



result-type 



\ — H ordinal-type-identifier 
k 



real - type- identi f ier 



~> 



> pointer-type-identifier 



1. 



The syntax for a formal-parameter-list is given in Section 7.3. 

A function is activated by the evaluation of a function-call (see Section 5.2), 
which gives the function's identifier and any actual-parameters required by the 
function. The function-call appears as an operand in an expression. The 
expression is evaluated by executing the function, and replacing the function- 
call with the value returned by the function. 

The statements to be executed upon activation of the function are specified by 
the statement-part of the function's block. This block should normally contain 
at least one assignment-statement (see Section 6.1.1) that assigns a value to 
the function-identifier. The result of the function is the last value assigned. 
If no such assignment-statement exists, or if it exists but is not executed, the 
value returned by the function is unspecified. 
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If the function's identifier is used in a function-call within the function's 
block, the function is executed recunively. 

Examples of function-declarations: 

function niax(a: vector; n: integer): real; 
var X: real; i: integer; 
begin 

X := a[l]; 

f or i := 2 to n do if X < a[i] then x := a[i] 

max := X 
end; 

function poi»er(x: real; y: integer): real; { y >= 0> 
var i^z: real; i: integer; 
begin 

W :=)C z :=1; i :=y; 
while i > do begin 
{z*(»**i) = X *« y } 
if odd(i) then z := z*i»; 
i := i div 2; 
« := sqr(«) 
end; 

{z = x**y } 
power := z 
end; 

A function can be declared forward in the same manner as a procedure (see 
Section 7.1 above). This permits mutual recursion. 

A function-declaration that has external instead of a block defines the Pascal 
Interface to a separately compiled or assembled external routine (a PUNC In 
the case of assembly language). See the explanation in Section 7.1 above. 

73 Parameten 

A formal-parameter- list may be part of a procedure-declaration or 
function-declaration, or it may be part of the declaration of a procedural or 
functional parameter. 

If it is part of a procedure-declaration or function-declaration, it declares the 
formal parameters of the procedure or function. Each parameter so declared 
is local to the procedure or function being declared, and can be referenced by 
its identifier in the block associated with the procedure or function. 

If it is part of the declaration of a procedural or functional parameter, it 
declares the formal parameters of the procedural or functional parameter. In 
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this case there is no associated block and the identifiers of parameters in the 
formal-parameter-list are not significant (see Sections 7.3.3 and 7.3.4 below). 



formal -paiameter-ljst 



parameter-declaration 



"•^ procedure-heading 



^ function-heading 



O 



T~^ 



^ 



<)>-^ 



paranieter-aeciaiauon ^ | laenUfier-liirh ^Q-^ r^ype-idenUfier 



var 



There are four kinds of parameters: value parameten, variable parameters, 
procedural par&neters, and functional parameters. They are distinguished as 
follows: 

• A parameter-group preceded by var is a list of variable parameters. 

• A parameter-group without a preceding var is a list of value parameters. 

• A procedure-heading or function-heading denotes a procedural or functional 
parameter; see Sections 7.3.3 and 7.3.4 below. 

NOTE 

The types of formal-parameters are denoted by type-identifiers. In 
other words, only a simple identifier can be used to denote a type in a 
formal-parameter-list To use a type such as arra>(0..255] of char as 
the type of a parameter, you must declare a type-identifier for this 
type: 

type charray = array [0.. 255] of char; 

The identifier charray can then be used In a formal-parameter-list to 
denote the type. 
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NOTE 

The word file (for an "untyped" file) Is not allowed as a type-Identifier 
in a parameter-declaratloa since it is a reserved word. To use a 
parameter of this type, declare some other identifier for the type file 
—for example, 

type phyle = f ile; 

The Identifier phyle can then be used in a formal-parameter-list to 
denote the type file. 

7.3.1 Value Parameters 

For a value-parameter^ the corresponding actual-parameter in a procedure- 
statement or function-call (see Sections 5.2 and 6.1.2) must be an expression, 
and its value must not be of file-type or of any structured-type that contains 
a file-type. The formal value-parameter denotes a variable local to the 
procedure or function. The current value of the expression is assigned to the 
formal value-parameter upon activation of the procedure or function. The 
actual-parameter must be assignment-compatible with the type of the formal 
value-parameter. 

7.3.2 Variable Parameters 

For a variable-parameter, the corresponding actual-parameter in a procedure- 
statement or function-call (see Sections 5.2 and 6.1.2) must be a variable- 
reference. The formal variable-parameter denotes this actual variable during 
the entire activation of the procedure or function. 

Within the procedure or function, any reference to the formal variable- 
parameter is a reference to the actual -parameter itself. The type of the 
actual-parameter must be Identical to that of the formal variable-parameter. 

NOTTE 

If the reference to an actual variable-parameter involves indexing an 
array or finding the object of a pointer, these actions are executed 
before the activation of the procedure or function. 

Components of variables of any packed structured type (including string-types) 
cannot be used as actual variable parameters. 

7.3.3 Procedural Parameten 

When the formal-parameter is a procedure-heading, the corresponding actual- 
parameter in a procedure-statement or function-call (see Sections 5.2 and 6.1.2) 
must be a procedure-identifier. The identifier in the formal procedure-heading 
represents the actual procedure during execution of the procedure or function 
receiving the procedural parameter. 
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ExmyjJe of proceaural parameters: 

program passProc; 
var i: integer; 

prcx^edure a(procedure x) {x is a formal procedural parameter.} 
begin 

writeC About to call x *); 

X {call the procedure passed as parameter} 
end; 

procedure b; 
begin 

writeCln procedure b') 
end; 

function c(procedure x): integer; 
begin 
x; {call the procedure passed as parameter} 

C:=2 

end; 

begin 

a(b); {call a, passing b as parameter} 

i:= c(b) {call c, passing b as parameter} 
end. 

If the actual procedure and the formal procedure have formal-parameter-lists, 
the formal-parameter-lists must be compatible (see Section 7.3.5). However, 
only the identifier of the actual procedure is written as an actual parameter; 
any formal-parameter-list is omitted. 

ExamjpJe of procedural parameters witn their own formai-parameter-lists: 

program test; 
procedure xAsPar(y: integer); 
begin 

(»ritelnCy=', y) 
end; 

procedure callProc(procedure xAgain(z: integer)); 
begin 

xftgain(l) 
end; 

begin {body of program} 

callProc(xAsPar) 
end. 

If the procedural parameter, upon activation, accesses any non-local entity (by 
variable-reference, procedure-statement, function-call, or label), the entity 
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accessed must be one that was accessible to the procedure when the procedure 
was passed as an actual parameter. 

To see what this means^ consider a procedure pp which is known to another 
procedure, flntPasser. Suppose that the following sequence takes place: 

1. firstPasser is executing. 

2. firstPasser calls a procedure named fintReceiver, passing pp as an 
actual parameter. 

3. firstReceiver calls secondReceiver, again passing pp as an actual 
parameter. 

k. secondReceiver calls pp (first execution of pp). 

5. secondReceiver calls thirdReceiver, again passing pp as an actual 
parameter. 

6. thirdReceiver calls firstPasser (indirect recursion), and passes pp to 
firstPasser as an actual parameter. 

7. firstPasser (executing recursively) calls pp (second execution of pp). 

Thus the procedure pp is called first from secondReceiver, and then from the 
second (recursive) execution of firstPasser. 

Suppose that pp accesses an entity named xkx, which is not local to pp; and 
suppose that each of the other procedures has a local entity named xxx. 

Each time pp is called, which xxx does it access? The answer is that in eacn 
case, pp accesses the xxx that is local to the first execution of flrstPasser— 
that is, the xxx that was accessible when pp was originally passed as an actual 
parameter. 

7.3.4 Functional Parameters 

When the formal parameter is a function-heading, the actual-parameter must 
be a function-identifier. The identifier in the formal function-heading 
represents the actual function during the execution of the procedure or 
function receiving the functional parameter. 

Functional parameters are exactly like procedural parameters, with the 
additional rule that corresponding formal and actual functions must have 
Identical result- types. 

733 Parameter List Compatibility 

Parameter list compatibility is required of the parameter lists of corresponding 
formal and actual procedural or functional parameters. 
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Two formal-parameter-lists are compatible if they contain the same number of 
parameters and if the parameters in corresponding positions match. Two 
parameters match if one of the following is true: 

• They are both value parameters of identical type. 

• They are both variable parameters of Icf&itlcal type. 

• They are both procedural parameters with compatible parameter lists. 

• They are both functional parameters with compatible parameter lists and 
identical result-types. 



7-10 



NOTES 



Chapter 8 
Programs 



8.1 Syntax 8-1 

8l2 Program-Parameters 8-1 

8.3 Segmentation 8-1 



029-(M00-A 



Programs 



8.1 Syntax 

A Pascal program has the form of a procedure declaration except for its 
heading and an optional uses-clausa 

program-heading ~^\Sy~\ 



uses-clause 



W^ 



block 



progjam-neaaing 



— »(prDgram3-» identifier 



T 



^'-(xy^ program-parameters -^(Sj 



pixxjiwn-paicfneteis 



identifier-list 



uses-clause 



»(uses^ 



identifier- list 



The occurrence of an identifier immediately after the word program declares it 
as the program's identifier. 

The uses-clause identifies all units required Xi'j the program, including units 
that it uses directly and other units that are used by those units. 

&2 Program-Parameten 

Currently, any program-parameters are purely decorative and are totally 
Ignored by the compiler. 

8.3 Segmentation 

The code of a program's main body is always placed in a run-time segment 
whose name is a string of blanks (the "blank segment"). Any other block can 
be placed in a different segment by using the $S compiler command (see 
Chapter 12 and Appendix A). If no $S command is used In the program, all 
code is placed in the blank segment. Code from a program can be placed in 
the same segment with code from a regular-unit, but it cannot be mixed with 
code from an intrinsic-unit (see Chapter 9). 
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9.1 Regular-units 9-1 

9.1.1 Writing Regular-Units 9-1 

9.1.2 Using Regular-Units 9-3 

9.2 Intrinsic-units 9-4 

9.3 Units that Use Other units 9-4 
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A unit Is a separately compiled, non-executable object file that can be linked 
with other object files to produce complete programs. There are two kinds of 
units, called regular-units ^s^ Intrinsic-units. In the current implementation of 
the Workshop, you can use intrinsic-units that are provided, but you cannot 
write new ones. 

Each unit used by a program (or another unit) must be compiled, and its object 
file must be accessible to the compiler, before the host program (or unit) can 
be compiled. 

9.1 Regular-Units 

Regular-units can be used as a means of modularizing large programs, or of 
making code available for incorporation in various programs, without making 
the source available. 

When a program or unit (called the host) uses a regular-unit, the linker inserts 
a copy of the compiled code from the regular-unit Into the host's object file. 

By default, the code copied from the regular-unit is placed in the blank 
segment (see Chapter 8). The code of the entire unit, or of blocks within the 
unit, can be placed in one or more different segments Xy^ using the $S compiler 
command (see Chapter 12). 

9.1.1 wnung Regular-Units 

The syntax for a regular-unit is: 



iSamztm H unit-heading | -»(7) 



J 



^ interface-part -^ implementation-part -» (end) -»(T) — ► 



""'^-^^"<1 KfTifiD- H IdenUfler 
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MMmezmL^^^^^ 



J 



^ 



<■ 



uses-clause 



D 



constant-declaration-part 



D 



^•^ type-declaration-part 



b 



^•^ varlable-declaratlon-part 



'^ 



b 



^ procedure-and-function-declaratlon-part 



Implementation-pan ^ f^ InplementatlorTy 



T 



''^ constant-declaration-part 



r 



"•^ type-declaration-part 



b 



r 



b 



"•^ variable-declaration-part 



r 



b 



^ procedure-and-functlon-declaration-part 



1^ 



me lnt£rface-part declares constants, types, variables, procedures, and 
functions that are "public," i.e. available to the host. 

The host can access these entities just as if they had been declared in the 
host Procedures and functions declared in the interface-part are abbreviated 
to nothing but the procedure or function name, parameter specifications, and 
function result-type. 

NOTTE 

Since the interface-part may contain a uses-clause, a unit can use 
another unit (see Section 9.3). 
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The implementation-part, which follows the last declaration in the interface- 
part, begins by declaring any constants, types, variables, procedures, or 
functions that are "private," i.e. not available to the host 

The public procedures and functions are re-declared in the implementation- 
part. The parameters and function result types are omitted from these 
declarations, since they were declared in the interface-part, and the procedure 
and function blocks, omitted in the Interface-part, are included in the 
implementation-part. 

In effect, the procedure and function declarations in the interface are like 
forward declarations, although the forward directive is not used. Therefore, 
these procedures and functions can be defined and referenced in any sequence 
in the implementation. 

NOTES 

There is no "initialization" section in Pascal units on the Lisa (unlike 
Apple II and Apple III Pascal). If a unit requires initialization of its 
data, it should define a public procedure that performs the initialization, 
and the host should call this procedure. 

Also note that global labels cannot be declared in a unit 



A short example of a unit is: 

unit Simple; 

INTERFACE {public Objects declared} 

const FlrstValue=l; 

procedure /VcldOne(var Incr : integer ); 

function Addl(Incr : integer) : integer; 

IMPLEMENTATION 

procedure AddOne; {note lack of parameters...} 
begin 

Incr:=Incr*l 
end; 
function Addl; {...and lack of function result type} 
begin 

Addl:=Incr*l 
end 
end. 

9.1.2 Using Regular-units 

The syntax for a uses-clause is given In Section 8.1. Note that in a host 
program, the uses-clause (if any) must Immediately follow the program- 
heading. In a host unit, the uses-clause (if any) immediately follows the 
symbol interface. Only one uses-clause may appear in any host program or 
unit; it declares all units used by the host program or unit 

See Section 9.3 for the case where a host uses a unit that uses another unit 
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It is necessary to specify the file to be searched for regular units. The $U 
compiler command specifies this file. See Chapter 12 for more details. 

Assume that the example unit Simple (see above) is compiled to an object file 
named APPLrSIMPLE.CBJ. The following is a short program that uses Simple. 
It also uses another unit nanned Other^ which is in file APPL:OTHER.0BJ. 



program CallSimple; 

uses {$U /tfVL: SIMPLE. OBJ} 
Simple^ 

{$U APPL:OTHER.OBJ} 
Other; 
var irint^r; 
begin 
l:=FirstValue; 
writeCi+1 is ',Addl(i)); 
•rite(xyz(i)) 
end. 



{file to search for units} 
{use unit Simple} 
{file to search for units} 
{use unit Other} 



{FirstValue is from Sinple} 
{Addl is defined in Simple} 
{xyz is defined in Other} 



92 Intrinsic-units 

The only intrinsic-units you can use are the ones provided with the Workshop 
software. 

Intrinsic-units provide a mechanism for Pascal programs to share common code, 
with only one copy of the code in the system. The code is kept on disk, and 
when loaded into memory it can be executed by any program that declares the 
intrinsic-unit (via a uses-clause, the same as for regular-units). 

By default, the system looks up all intrinsic-units in the system intrinsics 
library file, INTRINSIC.LIB. All intrinsic-units are referenced in this library, 
so the $U filename compiler command is not needed with intrinsic-units. 

9.3 Units that Use Other Units 

As explained above, the uses-clause in the host must name all units that are 
used by the host. Here "used" means that the host directly references 
something in the interface of the unit Consider the following diagram: 



Host Program 
uses unitA, unitB; 





unitA 


Jl 


interface 
uses unitC; 


\/ 


innplennentation 


V 




N, 


unite 


^ 


interface 




implementation 



unite 



interface 



implementation 
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The host program directly references the Interfaces of unitA and unltB; the 
uses-clause names both of these units. The Implementation-part of unitA also 
references the interface of unite, but it is not necessary to name unite in the 
host-program's uses-clause. 

In some cases, the uses-clause must also name a unit that is not directly 
referenced by the host. The following diagram is exactly like the previous one 
except that this time the interface of unitA references the Interface of unite, 
and unite must be named in the host-program's uses-clause. Note that unite 
must be named t)efore unitA. 



Host Program 
uses unite, unltA, 
unitB; 



unltA 



interface 
uses urutC; 



implementation 



unite 



interface 



implementation 



unite 



interface 



implemenlatlon 



In a case like this, the documentation for unltA should state that unite must 
be named in the uses-clause before unitA. 
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This chapter describes the standard C'hullt-in") I/O procedures and functions of 
Pascal on the Lisa. 

Standard procedures and functions are predeclared. Since all predeclared 
entities act as if they were declared in a "block" surrounding the program, no 
conflict arises from a declaration that redefines the same identifier within the 
program. 

NOTE 

Standard procedures and functions cannot be used as actual procedural 
and functional parameters. 

This chapter and Chapter 11 use a modified BNF notation. Instead of syntax 
diagrams, to Indicate the syntax of actual-parameter-llsts for standard 
procedures and functions. 

ExarrpJe: 

Parameter List- ne«(p [, tl, ... t//]) 

This represents the syntax of the actual-parameter-list of the standard 
proceckjre new, as follows: 

• p, tl, and t/7 stand for actual-parameters. Notes on the types and 
interpretations of the parameters accompany the syntax description. 

• The notation tl, ... in means that any number of actual-parameters can 
appear here, separated by commas. 

• Square brackets [ ] indicate parts of the syntax that can be omitted. 

Thus the syntax shown here means that the p parameter is required. Any 
number of t parameters may appear, with separating commas, or there may be 
no t parameters. 

10.1 Introduction to I/D 

This section covers the I/O concepts and procedures that apply to all file types. 
This includes the types text (see Section 10.3) and "untyped" files (see Section 
10.4). 

To use a Pascal file variable (any variable whose type is a file-type), it must 
be associated with an external file. The external file may be a named 
collection of Information stored on a peripheral device, or (for certain file- 
types) it may be the peripheral device Itself. 

The association of a file variable with an external file is made by opening the 
file. An existing file is opened via the reset procedure, and a new file is 
created and opened via the rewrite procedure. 
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NOTTE 

Pascal on the Lisa does not provide automatic I/O checking. To check 
the result of any particular I/O operation^ use the loresult function 
described In Section 10.1.6. 



iai.l Ctevice Types 

For purposes of Pascal I/O^ there are two types of peripheral devices: 

• A flle-stwcturecl device is one that stores files of data^ such as a diskette. 

• A character device Is one whose Input and output are streams of Individual 
bytes, such as the Lisa screen and keyboard or a printer. 

lai^ External File Species 

There are three "species" of external files that can be used in Pascal I/O 
operations: 

• A datafile is any file that Is stored on a file-structured device and was 
z;^^ originally created in association with a file variable of type text 

• A textflJe is a file that Is stored on a file-structured device and was 
originally created in association with a file variable of type text Textfiles 
are stored in a specialized format (see Section 10.3). 

• A character device can be treated as a file. 

Table 10-1 summarizes the effects of all possible combinations of different file 
variable types and external file species. The "ordinary cases" in the table 
reflect the basic intent of the various file-types. Other connbinations, such as 
block-oriented access to a textfile via a variable of type file, are legal but 
may require cautious programming. 
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Table 10-1 

Combinations of File variable Types with External File Species 

and Categories 



var f: file of 

someType; 



var f : text; 



var f : file; 



Ordinary case. 



datafile 



After reset 
f ' - 1st record 
file. 



(Textfile format 
assumed!) After 
reset*, f " Is 
unspecified. 



Ordinary case. 
Block access. 



textfile 



(Textfile format 
not assumed!) 
After reset*, 
f ' = 1st record 
of file (as 
declared). 



Ordinary case. 
Textfile format 
assumed. After 
reset, f * is 
unspecified. 



(Textfile format 
not assumed!) 
Block access. 



character 
device 



After reset, 
f * = 1st char, 
from device 
(system waits for 
lt!)L I/O error If 
file record type 
not byte-sized. 



Ordinary case. 



After reset, 
f " is unspeci- 
fied (no wait 
for input char). 



Block access. 
If allowed by 
device. 



' In Uiese cases, the loiesult function will return a "warning" 
(i.e., a negative nurrtfer) immediately after the reset operation 



iai3 The Reset Procedure 

Opens an existing file. 

Parameter List: reset(f^ title) 

1. f Is a variable-reference that refers to a variable of file-type, 
must not be open. 



The file 



title Is an expression with a string value. The string should be a valid 
pathname for a file on a file-structured device, or a pathname for a 
character device. 
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NOTE 

Both parameten are required (unlike Apple II and Apple III Pascal, 
where the second parameter Is optional). 

Reset(f^ title) finds an existing external file with the pathname title, and 
associates f with this external file. (If there is no existing external file with 
the pathname title, an I/O error occurs; see Section 10.1.6.) 

If title is the pathname of a character device, then 

• Eof(f) becomes false. 

• If f is of type text, the value of f * is unspecified. The next read or readln 
on f will wait until a character is available for input, and begin reading 
with that character. 

• If f is of type file and the device Is one that allows block access, there is 
no file buffer variable f" and the "current file position" is set to the first 
block (block 0) of the file. If the device does not allow block access, an 
I/O error occurs (see Section 10.1.6). 

• If f is not of type text or file, its component-type must be a "byte-size" 
type such as the type -128-127. Note that char is not a byte-size type! If 
the component- type of f is not byte-size, an I/O error occurs (see Section 
10.1.6). 

If no I/O error occurs, the system waits until a character is available from 
the device and then assigns the character's 8-bit code to f ". 

If title is the pathname for an existing file on a file-structured device, then 

" Eof(f) becomes false if the external file is not empty. If the external file 
is enpty, eof(f) becomes trua 

• If f is not of type text or file, reset sets the "current file position" to the 
first record in the external file, and assigns the value of this record to the 
file buffer variable f *. If the external file is a textfile, the ioresult 
function will return a negative number as a warning (see Section 10.1.6). 

• If f is of type text, the value of f * is unspecified. If the file is a textfile, 
the next read or readln on f will begin at the first character of f. If the 
file is a datafile, it will be treated as if it were a textfile (see Section 
10.3) and the ioresult function will return a negative number as a warning 
(see Section 10.1.6)l 

• If f is of type file, there is no file buffer variable f" and the "current file 
position" is set to the first block O^lock O) of the file. 



10-4 



Pascal Reference Manual 



Input/Output 



iaL4 The Rewrite ProcedLire 

Creates and opens a new file. 

Parameter List: rew:ite(f^ title) 

1. f is a variable-reference that refers to a variable of file-type. 

2. title is an expression with a string value. The string should be a valid 
pathname for a file on a file-structured device, or a pathname for a 
character device. 

If f is already open, an I/O error occurs (see Section 10.1.6). 

If title is the pathname of a character device, then 

Eof(f) becomes false. 

Rewrlte(f, title) simply associates f with the device and opens f. 

The status of the device Is not affected. 

The value of f " becomes unspecified. 
If title is the pathname for a new file on a file-structured device, then 

Eof(f) becomes tiue. 

Rewrlte(f^ title) creates a new external file with the pathname title, and 
associates f with the external file. This is the only way to create a new 
external file. 

The species of the new external file is set according to the type of f~ 
"textfile" for type text, or "datafile" for any other type. 

The value of f * becomes unspecified. 

If f is not of type file, the "current file position" is set to Just before the 
fint record or character position of the new external file. 

If f is of type file, the "current file position" is set to block (the first 
block in the file). 

If f is subsequently closed with any option other than lock or crunch (see 
Section 10.1.5), the new external file is discarded at that time. Closing f 
with lock or canch is the only way to make the new external file 
permanent. 

If title is the pathname of an existing external file, the existing file will be 
discarded only when f is subsequently closed with the lock or cnnch option 
(see Section 10.1.5). 

Unspecified effects are caused if the current file position of a file f is altered 
while the file-buffer f " Is an actual variable parameter, or an element of the 
record-variable-reference list of a with-statement, or both. 
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iai5 TTie Close Procedure 

Closes a file. 

Parameter List- close(f {, option]) 

1. f is a variaDle-reference that refers to a variable of file-type. 

2. option (may be omitted) is an identifier from the list given below. If 
omitted, the effect is the same as using the identifier normal. 

Close(f, option) closes f, if f is open. The association between f and its 
external file is broken and the file system marks the external file "closed". If 
f Is not open, the close procedure has no effect 

The option parameter controls the disposition of the external file, if it is not a 
character device. If it is a character device, f is closed and the status of the 
device is unchanged. 

The identifiers that can be used as actual-parameters for option are as follows: 

• normal ~ If f was opened using rewrite, it is deleted from the directory. 
If f was opened with reset, it remains In the directory. This is the default 
option. In the case where the option parameter is omitted. 

• lock ~ If the external file was opened with rewrite, it is made permanent 
In the directory. 

If f was opened with rewrite and a title that matches an existing file, the 
old file is deleted (unless the safety switch is "on"). If the old file has the 
safety switch "on," it remains in the directory and the new file is deleted. 

If f was opened with reset, a normal close is done. 

• purge ~ The external file is deleted from the directory (unless the safety 
switch is "on"), in the special case of a file that already exists and is 
opened with rewrite, the original file remains in the directory, unchanged. 

• crunch ~ This is like lock except that it locks the end-of-file to the point 
of last access; i.e., everything after the last record or character accessed is 
thrown away. 

All closes regardless of the option will cause the file system to mark the 
external file "closed" and will make the value of f " unspecified. 

If a program terminates with a file open (i.e., if close is omitted), the system 
automatically closes the file with the normal option. 

NOTE 

If you open an existing file with reset and modify the file with any 
write operation, the contents are immediately changed no matter what 
close option you specify. 
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iai£ TTie loresittt Function 

Pascal on the Lisa does not provide automatic I/O checking. To check the 
result of any particular I/O operation, you must use the ioresult function. 

Result type: integer 

Paiameter List- no parameters 

Ioresult returns an Integer value which reflects the status of the last com- 
pleted I/O operation. The codes are given in the Workshop User's Gulcte for the 
Lisa. Note that the code indicates successful completion, positive codes 
indicate errors, and negative codes are "warnings" (see Table 10-1). 

Note that the codes returned by ioresult are not the same as the codes used in 
/Npple II and /\pple III Pascal. 

NOTES 

The read, neadln, write, and writeln procedures described in Section 10.3 
may actually perform multiple I/O operations on each call. After one of 
these procedures has executed, ioresult will return a code for the status 
of the last of the multiple operations. 

/Mso, beware of the following common error in diagnostic code: 

read(foo); 

•ritelnC * ioresult = ' , ioresult ) 

The intention is to write out the status of the read operation, but 
instead the status written out will be that of the write operation on the 
string 'ioresult-*. 

10.1.7 TTie Eof Function 

Detects the end of a file. 

Result Type: boolean 

Parameter List: eof [(f)] 

1. f is a variable-reference that refers to a variable of file-type. 

If the paraneter-list is omitted, the function is applied to the standard file 
Infxjt (see Section 10.3). 

After a get or put operation, eofl(f) returns taie if the current file position is 
beyond the last external file record, or the external file contains no records; 
otherwise, eof(f) returns false. Specifically, this means the following: 

• After a get eof(f) returns true if the get attempted to read beyond the last 
file record (or the file is empty). 

• After a put, eof(f) returns true if the record written by the put is now the 
last file record. 
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If f is a character device, eofl(f) will always return false. 

See Section 10.3 for the behavior of eof(f) after a read or readln operation. 

NOTE 

Whenever eofff) is true, the value of the file duffer variable f " is un- 
specified. 

102 Record-Oriented lA) 

This section covers the get, put, and seek procedures, which perform record- 
oriented I/O; that is, they consider a file to be a sequence of variables of the 
type specified in the file-type. These procedures are not allowed with files of 
type filR 

The effects of get and put are unspecified with files of type text, and seek has 
no effect with files of type text The text type is supported by specialized 
procedures described in Section 10.3. 

102.1 The Get Procedure 

Reads the next record in a file. 

Parameter List- get(f) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

If eof(f) is false, get(f) advances the current file position to the next file 
record, and assigns the value of this record to f . If no next component 
exists, then eof(f) becomes true, and the value of f * becomes unspecified. 

If eof(f) is true when get(f) is called, then eof(f) remains tiue, and the value of 
f * becomes unspecified. 

If the external file is a character device, eof(f) is always false and there is no 
"current file position." In this case, get(f) waits until a value is ready for input 
and then assigns the value to f *. 

10.22 The Put Procedure 

Writes the current record in a file. 

Parameter List- put(f) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

If eof(f) is false, put(f) advances the cunent file position to the next file 
record and then writes the value of f " to f at the new file position. If the 
new file position is beyond the end of the file, eof(f) becomes true, and the 
value of f * becomes unspecified. 

If eof(f) is true, put(f) appends the value of f * to the end of f and eof(f) 
remains true. 
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If the external file is a character device, ^eof(f) is always false, there Is no 
"current file position," and the value of f " is sent to the device. 

NOTE 

If put is called immediately after a file is opened with reset, the put 
will write the secofxf record of the file (since the reset sets the 
current position to the first record and put advances the position before 
writing). To get around this and write the first record, use the seek 
procedure (see Section 10.2.3). 

102.3 The Seek Procedure 

Allows access to an arbitrary record in a file. 

Parameter List- seek(f^ n) 

1. f is a variable-reference that refers to a variable of file-type. The file 
must be open. 

2. n is an expression with an Integer value that specifies a record number in 
the file. Note that records in files are numbered from 0. 

If the file is a character device or is of type text, seek does nothing, 
otherwise, seek(t n) affects the action of the next get or put from the file, 
forcing it to access file record n instead of the "next" record. Seek(f^ n) does 
not affect the file-buffer f ". 

A gel or put must be executed between seek calls. The result of two con- 
secutive seeks with no intervening get or put is unspecified. Immediately after 
a seek(f^ vii eof(f) will return false; a following get or put will cause eof to 
return the appropriate value. 

NOTE 

The record number specified in a seek call is not checked for validity. 
If the number is not the number of a record in the file and the program 
tries to get the specified record, the value of the file-buffer becomes 
unspecified and eof becomes true. 

10.3 Text-Oriented l/D 

This section describes input and output using file variables of the standard type 
text Note that in Pascal on the Lisa, the type text is distinct from file of 
char (see Section 3.2.4). 

When a text file is opened, the external file is Interpreted in a special way. It 
is considered to represent a sequence of characters, usually formatted into 
IJr^s by CR characters (ASCII 13). 

The Lisa keyboard and the Workshop screen appear to a Pascal program to be 
built-in files of type text named iniput and output respectively. These files 
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need not be declared and need not be opened with reset or rewrite, since they 
are always open. 

When a program Is taking input from Input, typed characters are echoed on the 
Workshop screen. In addition to the input file, the Lisa keyboard Is also 
represented as the character device -KEYBOARD. To get keyboard Input 
without echoing on the screen, you can open a file variable of type text with 
-KEYBOARD as the external file pathname. 

Other interactive devices can also be represented In Pascal programs as files of 
type text 

When a text file Is created on a file-structured device, the external file Is a 
textflle. It contains Information other than the actual sequence of characters 
represented, as follows: 

• The stored file is a sequence of 102a-byte pages. 

• Each page contains some number of complete lines of text and is padded 
with null characters (ASCII 0) after the last line. 

• Two 512-byte header blocks are also present at the beginning of the file. 

• A sequence of spaces In the text may be compressed into a two-byte code, 
namely a OLE character {f^ow 16) followed by a byte containing 32 plus 
the number of spaces represented. 

All of this special formatting is invisible to a Pascal program if the file Is 
accessed via a file variable of type text (but visible via a file variable of any 
other file-type). 

Certain things that can be done with a record-structured file are impossible 
with a file variable of type text 

• The seek procedure does nothing with a file variable of type text 

• The effects of get and put are unspecified with a file variable of type text 

• The contents of the file buffer variable are unspecified with a file variable 
of type text 

• A file variable of type text that Is opened with reset cannot be used for 
output, and one opened with rewrite cannot be used for Input Results are 
unspecified if either of these operations Is attempted. 

In place of these capabilities, text-oriented I/O provides the following: 

• Automatic conversion of each input CR character into a space. 

• The eoln function to detect when the end of an input line has been 
reached. 

• The read procedure, which can read char values, string values, packed array 
of char values, and numeric values (from textual representations). 
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• The write procedure^ which can write char values, string values, packed 
array of char values, numeric values, and boolean values (as textual 
representations). 

• Line-oriented reading and writing via the readln and wrlteln procedures. 

• The page procedure, which outputs a form-feed character to the external 
file. 

• Automatic conversion of input DLE-codes to the sequences of spaces that 
they represent. Note that output sequences of spaces are not converted to 
DLE-codes. 

• Automatic skipping of header blocks and null characters during Input 

• Automatic generation of textfile header blocks, and automatic padding of 
textfile pages with null characters on output. 

10.3.1 The Read Procedure 

Reads one or more values from a text file Into one or more program variables. 

Parameter List: read( [f, ] vl [, v2, ... v/?] ) 

The syntax of the parameter-list of read allows an indefinite number of 
actual-parameters. Consecutive actual-parameten are separated by commas, 
just as in a normal parameter- list 

1. f (may be omitted) is a variable- reference that refers to a variable of 
type text The file must be open. If f is omitted, the procedure reads 
from the standard text file Input, which represents the Lisa keyboard. 

2. vl ... v/7 are Input variables Each is a variable parameter, used as a 
destination for data read from the file. Each input variable must be a 
variable-reference that refers to a variable of one of the following types: 

• char, integer, or longlnt (or a subrange of one of these) 

• real 

• a string-type or a packed array of char type. 

These are the types of data that can be read (as textual representations) 
from a file. At least one input variable must be present 

Read(f^vl_„v/7) is equivalent to: 

begin 
read(f,vl); 

read(f^v/7) 
end 
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NOfTE 

Read can also be used to read from a file fll that Is not a text file. In 
this case read(fllp() is equivalent to: 

begin 

X := fil"; 

get(fii) 
end 



103.1.1 Read with a Char variable 

If f is of type text and v is of type char, the following things are true 
immediately after rEad(f^v): 

• Eof(f) will return true if the read attempted to read beyond the last 
character in the external file. 

• Eoln(f) will return true, and the value of v will be a space, if the character 
read was the CR character. EoIn(f) will also return true if eof(f) is true. 

ia3.l.2 Read with an Integer or Longint viable 

If f Is of type text and v is of type integer, subrange of integer, or longint, 
then read(f,v) implies the reading from f of a sequence of characten that form 
a signed whole number according to the syntax of Section 1.4 (except that 
hexadecimal notation is not allowed). If the value read Is assignment- 
compatible witii the type of v, it is assigned to v; otherwise an enor occun. 

In reading the sequence of characters, preceding blanks and CRs are skipped. 
Reading ceases as soon as a character is reached that, together with the 
characters already read, does not form part of a signed whole number. 

An error occurs if a signed whole number is not found after skipping any 
preceding blanks and CRs. 

If f Is of type text, the following things are true immediately after read(f,v> 

• Eof(f) will return true if the last character in the numeric string was the 
last character in the external file. 

• Eoln(f) will return taie If the last character in the numeric string was the 
last character on the line (not counting the CR character). EolnfO will also 
return true if eof(f) Is true. 

ia3.L3 Read with a Real variable 

If f is of type text and v is of type real, then rBad(f,v) implies the reading 
from f of a sequence of characters that represents a real value. The real 
value is assigned to the variable v. 

In reading the sequence of characters, preceding blanks and CRs are skipped. 
Reading ceases as soon as a character is reached that, together with the 
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characten already read, does not form a valid representation. A "valid 
representation" is either of the following: 

• A finite reaL integer, or longint value represented according to the 
signed-number syntax of Section \A (except that hexadecinnal notation is 
not allowed). An Integer or longint value is converted to type reaL 

• An infinite value or Nan represented as described in Appendix D. 

An error occurs if a valid representation is not found after skipping any 
preceding blanks and CRs. 

Immediately after read(f,v) where v is a real variable, the status of eof(f) and 
eoln(f) are the same as for an integer variable (see Section 10.3.1.2 above). 

103.1.4 Read with a String Variable 

If f is of type text and v is of string-type, then read(f,v) implies the reading 
from f of a sequence of characters up to tjut not including the next CR or 
the end of the file. The resulting character-string is assigned to v. An error 
occurs if the number of characters read exceeds the size attribute of v. 

NOTE 

Read with a string variable does not skip to the next line after reading, 
and the CR is left waiting in the input buffer. For this reason, you 
cannot use successive read calls to read a sequence of strings, as they 
will never get past the first CR ~ after the first read, each subsequent 
read will see the CR and will read a zero-length string. 

Instead, use readln to read string values (see Section 10.3.2). Readln 
skips to the beginning of the next line after reading. 

The following things are true immediately after read(f^v> 

• Eofl(f) will return true if the line read was the last line in the file. 

• Eoln(f) will always return tae. 

ia3.L5 Read with a Packed Array of Char variable 

If f is of type text and v is a packed array of char, then rBacl[f,v) implies the 
reading from f of a sequence of characters. Characters are read into 
successive character positions in v until all positions have been filled, or until 
a CR or the end of the file is encountered. If a CR or the end-of-file is 
encountered, it is not read into v; the remaining positions in v are filled with 
spaces. 
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ia3^ The Readln Procedure 

The readln procedure is an extension of read. Essentially it does the same 
thing as read, and then skips to the next line in the input file. 

Parameter List: The syntax of the parameter list of readln is the same as that 
of read, except as follows: 

• A readln call with no input variables is allowed. Example: 

readln( sourcef lie) 

• The parameter-list can be omitted altogether. 

If the first parameter does not specify a file, or if the parameter-list is 
omitted, the procedure reads from the standard file input, which represents the 
Lisa keyboard. 

Readln(fX with no input-variables, causes a skip to the beginning of the next 
line (if there is one, else to the end-of-file). 

Readln can oT^be used on a text file. Except for this restriction, 
readln(f,vl,.-.,v/7) is equivalent to: 

begin 

read(f,vl, v/7); 

readln(f) 
end 

The following things are true immediately after readln(f//), regardless of the 
type of V: 

• Eof(f) will return true if the line read was the last line in the external file. 

• Eoln(f) will always return false. 

1033 The Write Procedure 

Writes one or more values to a text file. 

Parameter List •rite([f, ] pi [^ p2^ ... p/?]) 

The syntax of the parameter list of write allows an indefinite number of 
actual-parameters. 

1. f (may be omitted) is a variable-reference that refen to a variable of 
type text The file must be open. If f is omitted, the procedure writes to 
the standard file output, which represents the Workshop screen. 

2. pi ... p/7are output-specs Each output-spec includes an output 
expresslcHi whose value is to be written to the file. As explained below, 
an output-spec may also contain specifications of field-width and number 
of decimal places. Each output expression must have a result of type 
integer, longint, real, boolean, char, a string-type, or a packed array of 
char type. These are the types of data that can be written (as textual 
representations) to a file. At least one output-spec must be present. 
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Wrlte(f^l^^/7) is equivalent to: 

begin 
•rite(f,pl); 

wite(f^p/7) 
end 

Immediately after write(f% both eof(f) and eoln(f) will return true. 

NOTE 

Write can also be used to write onto a file fll that is not a text file. 
In this case write(filp<) is equivalent to: 

begin 

fll" := X; 

put(fil) 
end 

103.3.1 Qitput-Specs 

Each output-spec has the form 

OutExpr [: Min Width [: DecPiaces] ] 

where OutExpr is an output expression. MinWidth and DecPiaces are 
expressions with integer or longint values. 

MinWidth specifies the minimum field widths with a default value that 
depends on the type of the value of OutExpr (see below). MinWidth should be 
greater than zero; otherwise^ the results are unspecified. Exactly MinWidth 
characters are written (using leading spaces If necessary), except when OutExpr 
has a rMT^ric value that requires more than MinWidth characters; In this 
case, enough characters are written to represent the value of OutExpr. 

DecPiaces specifies the number of decimal places in a fixed-point repre- 
sentation of a real value. It can be specified only If OutExpr has a real value, 
and if MinWidth is also specified. If DecPiaces is not specified, a floating- 
point representation Is written. 

10.33^ Write with a Char Value 

If OutExpr has a char value, the character Is written on the file f. The default 
value for MinWidth is one. 

10.333 Write with an Integer or Longint value 

If OutExpr has an integer or longint value, its decimal representation Is written 
on the file f. The default value for MinWidth Is 8. The representation consists 
of the digits representing the value, prefixed by a minus sign if the value Is 
negative, and any leading spaces that may be required to satisfy MinWidth. If 
the representation requires more than MinWidth characters, MinWidth Is 
ignored. 
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1033.4 Write with a Real V^ue 

If QutExpr has a real value, the ctefault value for MlnWldth is 12. 

If OutExpr has an Infinite value, it is output as a string of at least two "+*" 
characters or at least two '*-" characters. If OutExpr is a NaN, it is output as 
the character string "NaN", possibly followed by a string of characters enclosed 
by single-quotes. See Section 10.3.3.5 for details on string output 

If GutExpr has a zero value, it is represented as "0" or "-0". 

If QjtExpr has a finite value, its decimal representation is written on the file 
f. This representation is the nearest possible decimal representation, depending 
on MlnWidth and DecPlaces. If the unrounded value is exactly halfway 
between two possible representations, the representation whose least significant 
digit is even is written out. 

If DecPlaces is not specified, a floaUng-point representation is written as 
follows: 

• If MinWidth is less than 6, then its value is set to 6 (internally). This is the 
minimum usable width for writing a floating-point representation. 

" If the sign of the value of OutExpr is negative, a minus sign is written; 
otherwise, a space is written. 

• If MlnWidth > 8, the significant digits are written with one digit to the left 
of the decimal point and (MinWidth - 7) digits to the right of the decimal 
point. 

• If MinWidth < 8, the most significant digit is written and the decimal point 
is omitted. 

• The exponent is written as the letter "E", an explicit "♦" or "-" sign, and 
two digits. 

If Cfec^laces is specified, a fixed-point representation is written as follows: 

» Enough leading spaces are written to satisfy MinWidth. 

• If the value is negative, the minus sign "-" is written; if it is not negative, 
a space is written. 

• If DecPlaces > 0, the significant digits are written with the integer part of 
the value to the left of the decimal point The next DecPlaces digits are 
written to the right of the decimal point 

• If DecPlaces < 0, only the integer part of the value is written and no 
decimal point is written. 

103.33 write with a String value 

If the value of OutExpr Is of string type with length L, the default value for 
MinWidth is L If MinWidth>-L, the value Is written on the file f preceded by 
(MinWidth-L) spaces. If MinWidth<L, the first MinWidth characten of the 
string are written. 



10-16 



Pascal Reference Manual Input/Output 

103.3^ Write wltn a Packed Array of Char Value 

If E is Of type packed array of char, Uie effect Is the same as writing a string 
whose length Is the number of elements in the array. 

10.3.3.7 Write with a Boolean value 

If the value of OutExpr is of type txnlean, the string " TRUE" (with a leading 
space) or the string "FALSE" is written on the file f. The default value of 
MlnWldth Is 5. If MlnWldth>5, leading spaces are added; if MinWldth<5, the 
first MlnWldth characters of the string are written. This is equivalent to: 

wrlte(f, ■ TRUE': MlnWldth) 

or 
•rite(f, 'FALSE* :MinWidth) 

10.3.4 The Writeln Procedure 

The writeln procedure is an extension of write. Essentially it does the same 
thing as write, and then writes a CR character to the output file (ending the 
line). 

Parameter List- The syntax of the parameter list of writem is the same as 
that of write, except as follows: 

• A writeln call with no output-specs is allowed. Example: 

•riteln(oiitputflle) 

• The parameter-list can be omitted altogether. 

If the first parameter does not specify a file, or if the parameter-list is 
omitted, the procedure writes to the standard file output, which represents the 
Workshop screen. 

Writeln(<) writes a CR character to the file f. 

Writeln can onlyXie used on a text file. Except for this restriction, 
writeln(f4)l,-.^/7) is equivalent to: 

begin 

wite(f,pl,...^p/7)i; 

writeln(f) 
end 

Immediately after writeln(f% both eof(f) and eoln(f) will return true. 

1033 The Eoln Function 
Result Type: boolean 

Parameter List- eoln[(f)] 

1. f Is a variable-reference that refers to a variable of type text The file 
must be opea 

The actual-parameter-llst can be omitted entirely. In this case, the function Is 
applied to the standard file input (the Lisa keyboard). 
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Eoln(f) returns tine "if the end of a line has been reached in f." The meaning 
of this depends on whether the external file is a character device, on which I/O 
procedure was executed last, and on what type of variable was used to receive 
an input value. For details, see Sections 10.3.1 through 10.3.4. 

The end of the file is considered to be the end of a line; therefore eoln(f) will 
return true whenever eof(f) is true. 

10.3A The Page Procedure 
Parameter List' page(f) 

1. f is a variable-reference that refen to a variable of type text The file 
must be open. 

The actual -parameter f cannot be omitted. Page(f) outputs a form-feed 
character to the file f. This will cause a skip to the top of a new page when 
f is printed. 

Note that page(output) sends a form-feed to the Workshop screen, but in 
general this will not clear the screen. For methods of clearing the screen, see 
the Workshop User's Guicfe for the Lisa . 

103.7 Keyboard Testing and Screen CXnrsor Control 
103.7.1 TTie Keypress Function 

Tests the Lisa keyboard to see if it has a character awaiting input 

Parameter List- no parameters. 

Result Type: boolean. 

Keypress returns true if a character has been typed on the Lisa keyboard but 
has not yet been read, or false otherwise. This Is done by testing the 
typeahead queue; if the queue is empty, keypress is false, otherwise it is true. 

10.3.7 J2 The Gotoxy Pnxjsdure 

Moves the Workshop screen cursor to a specified location on the screen. 

Parameter UsL- gotoxy(>c y) 

1. X is an expression with an integer value. If x < 0, the value will be 
used; if x > 79, the value 79 will be used. 

2. y is an expression with an integer value. If y < 0, the value will be 
used; if y > 31, the value 31 will be used. 

Gotoxy()c y) moves the cursor to the point (x,y) on the screen. Note that the 
point (0,0) is the upper left comer of the screen. 

ia4 untyped File I/D 

Untyped file I/O operates on an "untyped file," i.e., a variable of type file (no 
component type). An untyped file is treated as a sequence of 512-byte t^locks; 
the bytes are not type-checked but considered as raw data This can be useful 
for applications where the data need not be interpreted at all during I/O 
operations. 
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The blocks in an untyped file are considered to be numbered sequentially 
starting with 0. The system keeps track of the curient block numt)er;Vr\\z is 
block immediately after the file is opened. Each time a block is read, the 
current block number is incremented. By default, each I/O operation begins at 
the current block number; however, an arbitrary block number can be specified. 

An untyped file has no file-buffer, and it cannot be used with get, put, or any 
of the text-oriented I/O procedures. It can only be used with reset, rewrite, 
close, eof, aid the blockread and blockwrlte functions described below. 

To use untyped file I/O, ai untyped file is opened with reset or rewrite, and 
the blockread and blcxikwrite functions are used for input and output. 

lOAl The Blockread Function 

Reads one or more 512-byte blocks of data from an untyped file to a program 
variable, and returns the number of blocks read. 

Result Type: integer 

Parameter List- blockread(f, datalxif, count \, blocknum]) 

1. f is a variable-reference that refers to a variable of type flla TTie file 
must be open. 

2. databuf is a variable-reference that refers to the variable into which the 
blocks of data will be read. The size and type of this variable are not 
checked; if it is not large enough to hold the data, other program data 
may be overwritten and the results are unpredictable. 

3. count is an expression with an integer value. It specifies the maximum 
number of blocks to be transferred. Blockread will read as many blocks 
as it can, up to this limit. 

4. blocknum (may be omitted) is an expression with an Integer value. It 
specifies the starting block number for the transfer. If it is omitted, the 
transfer begins with the current block. Thus the transfers are sequential 
if the blocknumber parameter is never used; if a blocknumber parameter 
is used, it provides random access to blocks. 

BlockreadCf, databuf, count, blocknum) reads blocks from f into databuf, starting 
at block blocknum. Count is the maximum number of blocks read; if the 
end-of-file is encountered before count blocks are read, the transfer ends at 
that point The value returned is the number of blocks actually read. 

If the last block in the file was read, the current block number is unspecified 
and eof(f) is true. Otherwise, eof(f) is false and the current block number is 
advanced to the block after the last block that was read. 
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10l4^ TTie Blockwrite Function 

Writes one or more 512-byte blocks of data from a program vari^le to an 
untyped file, and returns the numt)er of blocks written. 

Result Type: integer 

Parameter List- block«lte(f, databuf, count {, blocknum]) 

1. f is a variable-reference that refers to a variable of type file. The file 
must be open. 

2. databuf is a variable-reference that refers to the variable from which the 
blocks of data will be written. The size and type of this variable are not 
checked. 

3. count is an expression with an integer value. It specifies the maximum 
number of blocks to be transferred. Blockwrite will write as many blocks 
as it can, up to this limit 

4. blocknum (may be omitted) is an expression with an Integer value. It 
specifies the starting block number for the transfer. If it is omitted, the 
transfer begins with the current block. Thus the transfers are sequential 
if the blocknumber parameter is never used; if a blocknumber parameter 
is used, it provides random access to blocks. 

Blockwrlte(f, databuf^ county blocknum) writes blocks into f from datdbuf, 
starting at block blcnknum. CXwnt is the maximum number of blocks written; 
if disk space runs out before count blocks are written, the transfer ends at 
that point. The value returned is the number of blocks actually written. 

If disk space ran out, the current block number is unspecified. Otherwise, the 
current block number is advanced to the block after the last block that was 
written. 

NOTC 

Unlike Apple II and Apple III Pascal, this Pascal does not allow 
blockwrite to write a block at a position beyond the first position after 
the current end of the file. In other words, you cannot create a block 
file with gaps in it. 
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standard Procedures and 
Functions 

This chapter describes all the standard C'bullt-ln") procedures and functions In 
Pascal on the Lisa, except for the I/O procedures and functions described in 
Chapter 10. 

Standard procedures and functions are predeclared. Since all predeclared 
entitles act as if they were declared In a block surrounding the program, no 
conflict arises from a declaration that redefines the same Identifier within the 
program. 

NOTE 

Standard procedures and functions cannot be used as actual procedural 
and functional parameters. 

This chapter uses a modified BNF notation. Instead of syntax diagrams, to 
Indicate the syntax of actual-parameter-llsts for standard procedures and 
functions. The notation is explained at the beginning of Chapter 10. 

11.1 Exit and Halt Procedures 
11.1.1 The Exit Procedure 

Exits Immediately from a specified procedure or function, or from the main 
program. 

Parameter List' exit (id) 

1. id Is the Identifier of a procedure or function, or of the main program. If 
id is an Identifier defined In the program. It must be In the scope of the 
exit call. Note that this Is more restricted than UCSD Pascal. 

Exit(id) causes an Immediate exit from id. Essentially, It causes a jump to the 
end of id. 

NOTE 

The halt procedure (see below) can be used to exit the main program 
from a unit without knowing the main program's identifier. 

ILI^ The Halt Procedure 

Exits Immediately from the main program. 

Parameter List: no parameters 

Halt causes an Immediate exit from the main program. 

11.2 Dynamic Allocation Procedures 

These procedures are used to manage the heep, a memory area that is 
unallocated when the program starts running. The procedure new is used for 
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all allocation of heap space by the program. The mark and release procedures 
are used together to deallocate heap space^ and the heapiesult function Is used 
to return the status of the last preceding dynamic allocation operation.. 

11.Z1 The New Procedure 

Allocates a new dynamic variable and sets a pointer variable to point to it 

Parameter List- ne«»(p \, XX ... t/?]) 

1. p is a variable-reference that refers to a variable of any pointer-type. 
This is a variable parameter. 

2. tl, ... t/7are constants^ used only when allocating a variable of 
record-type with variants (see below). 

Fvlew(p) allocates a new variable of the base-type of p, and makes p point to It. 
The variable can be referenced as p". Successive calls to new allocate 
contiguous areas. 

If the heap does not contain enough free space to allocate the new variable, p 
is set to nil and a subsequent call to the heapresult function will return a 
non-zero result 

If the base-type of p is a record-type with variants, new(p) allocates enough 
space to allow for the largest variant The form 

newCp, tl, ...t/7) 

allocates a variable with space for the variants specified by the tag values tl, 
... t/7 (instead of enough space for the largest variants). The tag values must 
be constants. They must be listed contiguously and in the order of their 
declaration. The tag values are not assigned to the tag-fields by this 
procedure. 

Trailing tag values can be omitted. The space allocated allows for the largest 
variants for all tag-values that are not specified. 

WARNflNG 

When a record variable is dynamically allocated with explicit tag values 
as shown above, you should not make assignments to any fields of 
variants that are not selected by the tag values. Also, you should not 
assign an entire record to this record. If you do either of these things, 
other data cm be overwritten without any error being detected at 
compile time. 
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112.2 "me Heapresult Function 

Returns the status of the most recent dynamic allocation operation. 

Result Type: integer 

Parameter List- no parameters 

Heapresult returns an integer code that reflects the status of the most recent 
call on new^ mark, release^ or memavall. The codes are given in the y^orkshcp 
User's Guide; note that the code for a successful operation Is 0. 

11.2.3 TTie Mark Procedure 

Sets a pointer to a heap area. 

Parameter List: inark(p) 

1. p is a variable-reference that refers to a variable of any pointer-type. 
This is a variable parameter. 

Mark(p) causes the pointer p to point to the lowest free area in the heap. The 
next call to new will allocate space beginning at the bottom of this area, and 
then p will be a pointer to this space. The pointer p is also placed on a 
stack-like list for subsequent use with the release procedure (see below). 

11.2.4 TTie Release Procedure 

Deallocates all variables in a marked heap area 

Parameter List release(p) 

1. p is a variable-reference that refers to a pointer variable. It must be a 
pointer that was previously set with the mark procedure. The pointer p 
must be on the list created by the mark procedure; otherwise an error 
occun. 

Release(p) removes pointers from the list, back to and including the pointer p. 
The heap areas pointed to by these pointers are deallocated. In other words, 
release(p) deallocates all areas allocated since the the pointer p was passed to 
the mark procedure. 

11.23 TTie Memavall Function 

Returns the maximum possible amount of available memory. 

Result Type: longint 

Parameter List: no parameters 

Memavall returns the maximum number of words (not bytes) of heap and stack 
space that could ever be available to the program, allowing for possible 
automatic expansion of the program's data segment Note that the result of 
memavall can change over time even if the program does not allocate any 
heap space, because of activities by the operating system or other processes in 
the system. 
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113 Transfer Functions 

The procedures pack and unpack, described by Jensen and Wirth^ are not 
supported. 

11.3.1 The Trunc Function 

Converts a real value to a longint value. 

Result Type: longint 

Parmteter List: trunc(x) 

1. X is an expression with a value of type real. 

Tnfic(x) returns a longint result that is the value of x rounded to the largest 
whole number that is between and x (inclusive). 

113.2 The Round Function 

Converts a real value to a longint value. 

Result Type: longint 

Parameter List- round(x) 

1. X is an expression with a value of type real. 

Round(x) returns a longint result that is the value of x rounded to the nearest 
whole nunnber. If x is exactly halfway between two whole numbers, the result 
is the whole number with the greatest absolute magnitude. 

11.33 The Qrd4 FuncUon 

Converts an ordinal-type or pointer-type value to type longint 

Result Type: longint 

Parameter List- ord4(x) 

1. x is an e)q3ression with a value of ordinal-type or pointer-type. 

Qrda(x) returns the value of x converted to type longlnL If x is of type 
longint, the result is the same as x 

If x is of pointer- type, the result is the corresponding physical address, of type 
longint 

If x is of type integer, the result is the same numerical value represented by )c 
but of type longint This is useful in arithmetic expressions. For example, 
consider the expression 

adc*)^ 

where both ado and ycfz are of type integer. By Uie rules given in Section 
5.1.1.2, the result of this multiplication is of type integer (16 bits), if the 
mathematical product of ado and xyz cannot be represented in 16 bHs, the 
result is the low-order 16 bits. To avoid this, the expression can be written as 

ord4(abc)*xyz 
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This expression causes 32-bit arithmetic to be used, and the result is a 32-bit 
longint value. 

If X is of an ordinal-type other than integer or longint, the numerical value of 
the result is the ordinal number determined by mapping the values of the type 
onto consecutive non-negative integers starting at zero. 

113.4 The Pointer Function 

Converts an integer or longint value to pointer-type. 

Result Type: pointer 

Parameter List' pointer(x) 

1. X is an expression with a value of type integer or longint 

Pointer(x) returns a pointer value that corresponds to the physical address x. 
This pointer is of the same type as nil and is assignment-compatible with any 
pointer-type. 

11.4 Arithmetic Functions 

In general, any real result returned by an arithmetic function is an approx- 
imation. There are two exceptions to this: the result of the abs function is 
exact, and the result of the pwroften function is exact when the parameter n 
is in the range < n < 10. 

1L4.1 TTie Odd FuncUon 

Tests whether a whole-number value is odd. 

Result Type: boolean 
Parameter List- odd(x) 

1. x is an expression with a value of type Integer or longint 
Odd(x) returns true if x is odd; otherwise it yields false. 

11.42 The Ate Function 

Returns the absolute value of a numeric value. 

Result Type: same as parameter 
Parameter List' abs(x) 

1. X is an expression with a value of type real, integer, or longint 
Abs(x) returns the absolute value of x. 
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1L43 The Scpr Function 

Returns the square of a numeric valte. 

Result Type: depends on parameter (see below) 

Parameter List- sqr(x) 

1. X Is an expression with a value of type real^ integer^ or longint 

Sqi(x) returns the square of x. If x is of type real^ the result is real; If x is of 
type longint the result is longint; and if x is of type integer^ the result may be 
either integer or longint 

If X is of type real and floating-point overflow occurs^ the result Is +«. 

11A4 "me Sin Function 

Returns the sine of a numeric value. 

Result Type: real 

Parameter List: sin(x) 

1. X Is an expression with a value of type real, integer, or longint This 
value is assumed to represent an angle In radians. 

Sin(x) returns the sine of x If x Is infinite, a diagnostic NaN is produced and 
the Invalid operation signal Is set (see Appendix D). 

11-4.5 The Cos Function 

Returns the cosine of a numeric value. 

Re^t Type: real 

Parameter List- cos(x) 

1. X is an expression with a value of type real. Integer, or longint This 
value is assumed to represent an aigle in radians. 

Cos(x) returns the cosine of x If x is infinite, a diagnostic NaN is produced 
and the invalid operation signal is set (see Appendix D). 

11.4.6 The Exp Function 

Returns the exponential of a numeric value. 

Result Type: real 

Parameter List- exp(x) 

1. X Is an expression with a value of type real. Integer, or longint All 
possible values are valid. 

Exp(x) returns the value of e^, where e is the base of the natural logarithms. 
If floating-point overflow occun, the result is ♦«. 
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11A7 The Ln FuncUon 

Returns the natural logarithm of a numeric value. 

Result Type: real 

Parameter List- ln(x) 

1. X is an expression with a value of type real^ integer^ or longlnL All 
non-negative values are valid; negative values are invalid. 

If X is non-negative, ln(x) returns the natural logarithm (log^ ) of x. 

If X is negative, a diagnostic NaN is produced and the Invalid Operation signal 
is set (see Appendix D). 

11-4.8 Trie Sqrt Function 

Returns the square root of a numeric value. 

Result Type: real 

Parameter List: scjrt(x) 

1. X is an expression with a value of type real,. Integer, or longint All 
non-negative values are valid; negative values are Invalid. 

If X is non-negative, sqrt(x) returns the positive square root of x. 

If X is negative, a diagnostic NaN Is produced and the Invalid Operation signal 
is set (see Appendix D). 

lL4w9 The Arctan Function 

Returns the arctangent of a numeric value. 

Result Type: real 

Parameter List- arctan(x) 

1. X is an expression with a value of type real, integer, or longint All 
numeric values are valid. Including ±». 

Arctan(x) returns the principal value. In radians, of the arctangent of x. 

11.4.10 The Pwroften Function 

Returns a specified power of 10. 

Result Type: real 
Parameter List- p«roften(n) 
1. n Is an expression with a value of type integer. 

If -45 < n < 38, then pwroften(n) returns lO". The result is mathematically 
exact for < n < 10. If n < -46, the result Is 0; If n > 39, the result Is +~ 
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113 Ordinal Functions 
11.5.1 "me Qrd Function 

Returns the ordinal number of an ordinal-type or pointer-type value. 

Result Type: integer or longint 

Parameter List' ord(x) 

1. X is an expression with a value of ordinal- type or pointer- type. 

If X is of type Integer or longint, the result is the same as x 

If X is of pointer-type, the result is the corresponding physical address, of type 
longint 

If X is of another ordinal-type, the result is the ordinal number determined by 
maf^ing the values of the type onto consecutive non-negative whole numbers 
starting at zero. 

For a parameter of type char, the result is the corresponding ASCII code. For 
a parameter of type booleaa 

ord(false) returns 
ord(trtie) returns 1 

11.5^ T?ie Chr Function 

Returns the char value corresponding to a whole-number value. 

Result Type: char (but see below) 

Parameter List- chr(x) 

1. x is an expression with an integer or longint value. 

Chi(x) returns the char value whose ordinal number (i.e., its ASCII code) is x, if 
x is In the range 0..255. If x is not in the range a.255, the value returned is 
not within the range of the type char, and any attempt to assign it to a 
variable of type char will cause an error. 

For any char value ch, the following is true: 

chr(ord(ch)) = ch 

11.5.3 The Succ Function 

Returns the successor of a value of ordinal- type. 

Result Type: same as parameter (but see below) 

Parameter List' succ(x) 

1. x is an expression with a value of ordinal-type. 

Succ(x) returns the successor of x, if such a value exists according to the 
inherent ordering of values in the type of x 
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If X is the last value in the type of x, it has no successor. In this case the 
value returned is not within the range of the type of x. and any attempt to 
assign it to a variable of this type will cause unspecified results. 

113.4 The Pred Function 

Returns the predecessor of a value of ordinal-type. 

Result Type: same as parameter (hut see below) 

Parameter List: pred(x) 

1. x is an expression with a value of ordinal-type. 

Pred(x) returns the predecessor of x, if such a value exists according to the 
inherent ordering of values in the type of x. 

If X is the first value in the type of x, it has no predecessor. In this case the 
value returned is not within the range of the type of x. and any attempt to 
assign it to a variable of this type will cause unspecified results. 

11.6 String Procedures and Functions 

The string procedures and functions do not accept packed array of char 
parameters, and they do not accept indexed string parameters. 

11.6.1 The Length Function 

Returns the current length of a value of string-type. 

Result Type: integer 
Parameter List: lengtr<str) 

1. str is an expression with a value of string-type. 
Length(str) returns the cunent length of str. 

11-6.2 The Pos Function 

Searches a string for the first occurrence of a specified substring. 

Result Type: integer 

Parameter List: pos(substr, str) 

1. substr is an expression with a value of string-type. 

2. str is an expression with a value of string-type. 

Pos(stt)str, str) searches for substr within str, and returns an integer value that 
is the index of the first character of substr within str. 

If substr is not found, pos(substr, str) returns zero. 
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1L63 "me Concat Function 

Takes a sequence of strings and concatenates them. 

Result Type: string-type 

Parameter List' cofXjat(strl \, str2, ... str/?]) 

• Each parameter is an expression with a value of string-type. Any practical 
number of parameters may De passed. 

Concat(strl, -^ str/?) concatenates all the parameters in the order In which 
they are written^ and returns the concatenated string. Note that the number 
of characters In the result cannot exceed 255. 

11.6.4 The Copy Function 

Returns a substring of specified length, taken from a specified position within 
a string. 

Result Type: string-type 

Parameter List' copy( source^ inde>^ count) 

1. source Is an expression with a value of string-t)^. 

2. index is an expression with an integer value. 

3. count Is an expression with an integer value. 

Copy(source, lnde)c count) returns a string containing count characters from 
source, beginning at sourceflndex]. 

11A5 The Delete Procedure 

Deletes a substring of specified length from a specified position within the 
value of a string variable. 

Parameter List' delete(dest^ index, count) 

1. dest is a variable-reference that refers to a variable of string-type. This 
is a variable parameter. 

2. index is an expression with an Integer value. 

3. count Is an expression with an integer value. 

Delete(dest^ index, count) removes count characters from the value of dest 
beginning at dest[index} 

11^^ The Insert Procedure 

Inserts a substring into the value of a string variable, at a specified position. 

Parameter List: insert (source, dest, index) 

1. source Is an expression with a value of string-type. 

2. dest Is a variable-reference that refers to a variable of string-type. This 
Is a variable parameter. 

3. index is an expression with an integer value. 
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Insert(source, dest;, index) inserts source into dest The first character of 
source tjecomes dest(index]. 

11.7 Byte-Oriented Procedures and Functions 

These features allow a program to treat a program variable as a sequence of 
bytes^ without regard to data types. 

NOTE 

The sizeof function (described in Section 11.7.3, below) can be used to 
determine the number of bytes in a variable. 

These procedures do no type-checking on their source or dest actual- 
parameters. However^ since these are variable parameters they csurtot tje 
Indexed if they are packed or if they are of string-type. If an unpacked 
"byte array" is desired, then a variable of the type 

array [lo..hi] of -128.. 127 

should be used for source or dest The elements in an array of this type are 
stored in contiguous bytes, and, since it is unpacked, an array of this type can 
be used with an index as an actual-parameter for these routines. 

IMPLEMENTATION NOTE 

Currently, an array with elements of the type 0.255 or the type char 
has its elements stored in words, not bytes. 

11.7.1 The Moveleft Procedure 

Copies a specified number of contiguous bytes from a sojrce range to a 
destination range (starting at the lowest address). 

Parameter List- moveleft (source, dest, count) 

1. source is a variable-reference that refers to a variable of any type 
except a file-type or a structured-type that contains a file-type. This is 
a variable parameter. The first byte allocated to source (lowest address 
within source) is the fint byte of the source range. 

2. dest is a variable-reference that refers to a variable of any type except 
a file-type or a structured-type that contains a file-type. This is a 
variable parameter. The first byte allocated to dest (lowest address 
within dest) is the first byte of the destination range. 

3. count is an expression with an integer value. The source range and the 
destination range are each count bytes long. 

Moveleft(source„ dest, count) copies count bytes from the source range to the 
destination range. 
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Moveleft starts from the "left" end of the source range (lowest address). It 
proceeds to the "right" (higher addresses), copying bytes into the destination 
range^ starting at the lowest address of the destination range. 

The count parameter is not range-checked. 

11.7.2 The Moverlght Procedure 

Moveright is exactly like moveleft (see above), except that it starts from the 
"right" end of the source range (highest address). It proceeds to the "left" 
(lower addresses), copying bytes into the destination range, starting at the 
highest address of the destination range. 

The reason for having both rrwveleft and moverlght is that the source and 
destination ranges may overlap. If they overlap, the order in which bytes are 
moved is critical: each byte must be rroved before It gets overwritten by 
another byte. 

11.73 The Sizeof FuncUon 

Returns the number of bytes occupied by a specified variable, or by any 
variable of a specified type. 

Result Type: integer 

Parameter List: sizeof (id) 

1. id is either a variable-identifier or a type-identifier. It must not refer to 
a file-type or a structured-type that contains a file-type, or to a 
variable of such a type. 

Sizecrf(id) returns the number of bytes occupied by id, if id is a variable- 
identifier; if id is a type-identifier, it returns the number of bytes occupied by 
any variable of type id. 

11^ Packed Array of Char Procedures and Functions 

NOTE 

These routines operate only on packed arrays of char. The packed 
arrays of char cannot be subscripted; the operations always begin at the 
first character in a packed array of char. 

11.8.1 ine Scaneq Function 

Searches a packed array of char for the first occurrence of a specified 
character. 

Result Type: integer 

Parameter List- scaneq( limit, ch, paoc) 

1. limit is an expression with a value of type integer or longint It is 
truncated to 16 bits, and is not range-checked. 

2. ch is an expression with a value of type char. 
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3. paoc is an expression with a value of type packed array of char. This is 
a variable parameter. 

Scanec|(limlt, ch, paoc) scans paoc, looking for the first occurrence of ch. The 
scan begins with the first character in paoa If the character is not found 
within limit characters from the beginning of paoc, the value returned is equal 
to limit Otherwise, the value returned is the number of characters scanned 
before ch was found. 

1L8^ "me Scanne Function 

This function is exactly like scaneq, except that it searches for a character 
that does not match the ch parameter. 

11A3 The FiUchar Procedure 

Fills a specified number of characters in a packed array of char with a 
specified character. 

Parameter List- fillchar(paoc, count, ch) 

1. paoc is an expression with a value of type packed array of char. This is 
a variable parameter. 

2. count is an expression with a value of type integer or longint It is 
truncated to 16 bits, and is not range-checked. 

3. ch is an expression with a value of type char. 

FilIchai(paoc, count, ch) writes the value of ch into count contiguous bytes of 
memory, starting at the first byte of paoc. 

Since the count parameter is not range-checked, it is possible to write into 
merrrary outside of paoc, with unspecified results. 
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The Compiler 



The Pascal compiler translates Pascal source text to an Intermediate code, and 
the code generator translates the Intermediate code to MC6800D object code. 
Instructions for operating the compiler and code generator are given in the 
Workshop user's Guide for the Lisa 

12.1 Compiler Commands 

A compiler command is a text construction, embedded in source text, that 
controls compiler operation. Every compiler command is written within 
comment delimiters, {...} or (*...*). Every compiler command begins with the $ 
Character, which must be the first character inside the comment delimiters. 

In this manual, compiler commands are shown in upper case to help distinguish 
them from Pascal program text; however, upper and lower case are inter- 
changeable in compiler commands just as they are in Pascal program text. 

The following compiler commands are available: 

INPUT FILE CONTROL 

$1 filename start taking source code from file filename. When the end 
of this file is reached, revert to the previous source file. 
If the filename begins with + or -, there must be a space 
between $1 and the filename (the space Is not necessary 
otherwise). 

$U filename Search the file filename for any units subsequently 

specified In the uses-clause. Does not apply to Intrlnslc- 
mlts. 

CONTROL OF CODE GENERA TION 

SC* or $C- Turn code generation on (♦) or off (-). This Is done on a 
procedure-by-procedure basis. These commands should be 
written between procedures; results are unspecified If they 
are written Inside procedures. The default Is $C+. 

«0V* or IGV- Turn Integer overflow checking on (♦) or off (-). Overflow 
checking Is done after all Integer add, subtract, i6-blt 
multiply, divide, negate, abs, and l6-blt square operations, 
and after 32 to 16 bit conversions. The default is $GV- 

$R* or IR- Turn range checking on (♦) or off (-> At present, range 
checking Is done In assignment statements and array 
Indexes and for string value parameters. No range 
checking Is done for type lon^t The default Is $R*. 
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$s segnanre start putting code modules into segment segname. The 

default segment name Is a string of blanks to designate the 
"blank segment," In which the main program and all built-in 
support code are always linked. All other code can be 
placed into any segment. 

$x+ or $x- Turn automatic run- time stack expansion on (♦) or off (-). 
The default Is $X+. 

NOTE 

Compiler directives that affect code generation take effect when the 
end of the Pascal statement in which they are embedded is reached. If 
the same directive is specified more than once in a statement, the last 
setting is used. A tricky case of this is: 

begin 
J - foo; 
{«-> 
i := i«2 

end 

Since the second assignment does not end with a semicolon, and 
actually ends when the end is encountered, range checking will not be 
turned off for that statement. 



DEBUGGING 

$D* or ID- Turn the generation of procedure names In object code on 
(♦) or off (-). These commands should be written between 
procedures; results are unspecified if they are written 
inside procedures. The default Is ID*. 

CONDITIONAL COMPILATION 

$DECL list (see Section 12.2 below). 

$ELSEC (see Section 12.2 below). 

$ENDC (see Section 1Z.Z below). 

SIFC (see Section 12.2 below)L 

$SETC (see Section 12.2 below). 
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LISTING CONTROL 

$E filename Start making a listing of compiler errors as Xhey are 

encountered. Analogous to $L filename (see below). The 
default is no error listing. 

$L filename Start listing the compilation on file filename. If a listing 
is being made already, that file is closed and saved prior to 
opening the new file. The default is no listing. If the 
filename begins with ♦ or -, there must be a space between 
$L and the filename (the space is not necessary otherwise). 

SL* or $L- The first ♦or - following the $L turns the source listing on 
(♦) or off (-) without changing the list file. You must 
specify the listing file before using $L+. The default is 
$L*, but no listing is produced if no listing file has been 
specified. 

122 CondlUonai Compilation 

Conditional compilation is controlled by the $IFC^ tELSEC, and $ENDC 
commands, which are used to bracket sections of source text. Whether a 
particular bracketed section of a program Is complied depends on the boolean 
value of a complie-Ume expression which can contain complie-tlme variaoies 

12^.1 Compile-Time Variables and trie $OECL Command 

Compile-time variables are connpletely Independent of program variables; even 
if a compile-time variable and a program variable have the same identifier, 
they can never be confused by the compiler. 

A compile-time variable is declared when it appears in the identifier-list of a 
$DECL command. 

Example of compile-time variaOle declaration: 

{lOECL LIBVERSION, PROGVERSION} 

This declares LIBVERSIGN and PROGVERSION as compile-time variables. 
Notice that no types are specified. 

Note the following points about complle-tlme variables: 

• Compile-time variables have no types, although their values do. The only 
possible types are integer and boolean. 

• All complle-tlme variables should be declared before the end of the 
varlable-declaratlon-part of the main program. In other words a lOECL 
command that declares a new complle-tlme variable must precede the 
main program's procedure and function declarations (if any). The new 
compile-time variable Is then known throughout the remainder of the 
compilation. 

• At any point in the program^ a compile-time variable can have a new 
value assigned to it by a $SETC command. 
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1222. Trie $SETC command 

The tSETC command has the form 

{$SETC ID := EXPR} 

or 

{$SETC ID = EXPR} 

Where ID is the identifier of a compile-time variable and EXPR is a compile- 
tlme expression. EXPR is evaluated immediately. The value of EXPR Is 
assigned to ID. 

Example of assignment to complle-tlme varlattle: 

{$SETC LIBVERSION := 5} 

This assigns the value 5 to the compile-time variable LIBVERSION. 

12.23 Compile-Time Expressions 

Complle-tlme expressions appear In the $SETC command and in the $IFC 
command. A compile-time expression is evaluated by the compiler as soon as 
it Is encountered in the text. 

The only operands allowed In a compile-time expression are: 

• Compile-time variables 

• Constants of the types Integer and bcnlean. (These are also the only 
possible types for results of compile-time expressions.) 

All Pascal operators are allowed except as follows: 

• The in operator is not allowed. 

• The • operator is not allowed. 

• The / operator is automatically replaced by div. 

\22A The $IFC. lELSEC. and SEhCC commands 

The SELSEC and SENDC commands take no arguments. The $FC command has 
the form 

{$IFC EXPR} 

where EXPR is a complle-tlme expression with a boolean value. 

These three commands form constructions similar to the Pascal if-statement, 
except that the $ENDC command Is always needed at the end of the $FC 
construction. SELSEC is optional. 
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Example of concflUonally compJled code: 

{$IFC PROGVERSION >= LIBVERSION} 

k := kvall(data+indat); 
{SELSEC} 

k := kval2(data+cplndat " ); 
{$ENDC} 

•rlteln(k) 

If the value of PRCX3VERSI0N Is greater than or equal to the value of 
LIBVERSION^ then the statement k:-kvall(data+lnciat) Is compiled, and the 
statement k:-kval2(data*cplndat") Is skipped. 

But if the value of PROGVERSION is less than the value of LIBVERSIGN, then 
the first statement is skipped and the second statement is compiled. 

In either case, the wrlteln(k) statement is compiled because the conditional 
construction ends with the $ENDC command. 

$IFC constructions can De nested within each other to 10 levels. Every $IFC 
must have a matching $ENDC. 

When the compiler is skipping, all commands in the skipped text are ignored 
except the following: 

$ELSEC 
SENDC 

$IFC (so that SENDC's can be matched properly) 

All program text is ignored during skipping. If a listing is produced, each 
source line that is skipped is marked with the letter s as its "lex level." 

12.3 Optimization of If-Statements 

When the compiler finds an if-statement controlled by a boolean constant, it 
may be unnecessary to compile the then part or the else part. For example, 
given the declarations 

const always = true; 
never = false; 

then the statement 

If never then statement 

will not be compiled at all. In the statement 

if never then statement 1 
else statement2 

"statementl" is not compiled; only "statement2" is compiled. 
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Similarly^ In the statement 

if aH»ays then statement l 
else statement? 

only "statementl*' Is compiled. 

The Interaction between this optimization and conditional compilation can be 
seen from the following program: 

program Foo; 

{$SETC FLAG := FALSE} 

const pi = 3.1415926; 

Size = 512; 
{$IFC FLAG} 

debug = false; {a boolean constants if FLA6=triie} 

{$ENDC} 

var 1^ j^k^l^ntn: integer; 
{$IFC NOT FLAG} 

debug: boolean; {a boolean variable^ if FLAG=false} 
{$ENDC} 

{$IFC NOT FLAG} 
procedure whatmode; 

begin 
{interactive procedure to set global boolean variable, debug} 

end; 
{$ENDC} 

begin {main} 
{$IFC NOT FLAG} 

■hatmode; 
{$ENDC} 

If debug then begin 

statementl 
end 
else begin 

statementz 
end 

end. 

The way this Is compiled depends on the compile-time variable FLAG. If 
FLAG is false, then debug is a boolean [/ariable and the whatmode procedure 
is compiled and called at the beginning of the main program. The if debug 
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statement is controlled by a boolean variable and all of it is compiled, in the 
usual manner. 

But if the value of FLAG is changed to true, then debug is a constant with 
the value false, and whatmode is neither compiled nor called. The if debug 
statement is controlled by a constant, so only its else part, "statement2", is 
compiled. 

12.4 Optimization of While-Statements and Repeat-Statements 

A While-Statement or repeat-statement controlled by a boolean constant does 
not generate any conditional branches. 

12.5 Efficiency of Case-Statements 

A sparse or small case-statement will generate smaller and faster code than 
the corresponding sequence of if-statements. 
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Appendix A 
Comparison to Apple II and Apple III 

Pascal 



This appendix contains lists of the major differences between the Pascal 
language on the Lisa and the Pascal Implemented on the Apple II and Apple III. 
Please note that these lists are not exhaustive. 

A.1 Extensions 

The following features have Deen added on the Lisa: 

• ® Operator—returns the pointer to Its operand (see Section 5.1.6). 

• Heapresult pointer and orcw functions (see Sections 11.2.2^ 11.5.5^ and 
11.5.4X 

• Keypress function built into the language, with same effect as the keypress 
function In the applestuff unit of Apple II and Apple III Pascal (see Section 
10.3.7.1). 

• Hexadecimal constants (see Section 1.4). 

• Otherwise-clause In case-statement (same as Apple 111 Pascal; see Section 
6.2.2.2). 

■ Global goto-statement (see Section 6.1.3). 

• A file of char type that Is distinct from the text type (see Sections 3.2.4 
and 10.3). 

• Numerous compiler commands (see Section 12.1). 

• Procedural and functional parameters (see Sections 7.3.3 and 7.3.4). 

• Stronger type-checking (see Sections 3.4 and 7.3.5). 

• QuickDraw graphics and hardware Interface, Including mouse control (see 
Appendixes E and F). 

A.2 Deletions 

The following features are not Included on the Lisa: 

• Turtlegraprdcs, applestuft and other standard units of Apple 11 and Apple 
III Pascal. 

■ Interactive type (not needed, as the I/O procedures will do the right thing 
with a file of type text If It Is opened on a character device^ 

• Keyboard file—same effect can be obtained by opening a file of type text 
on the device -KEYBOARD (see Section 10.3). 
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• Unit (device-oriented) I/O procedures, such as UNITBUSY. 

• Recognition of the ETX character (control-c) to mean "end of file" in input 
from a character device. 

• "Long Integer data type, with length attribute In declaration. Replaced by 
the longint type (see Section 3.1.1.2)l 

• "Initialization" code in a unit (see Chapter % 

• The ability to create new intrinsic-units and install them in the system 
(see Chapter % 

• Reset procedure without an external file title, for use on a file that is 
already open (see Section 10.1.1). To obtain the same effect, close the file 
»Kl reopen it. 

• Treesearcfi. 

• Bytestream, wordstream (data types In Apple III Pascal). 

• Exit(program)— The exit(identifler) form works, and the identifier can be the 
program-identifier. Halt can also be used for orderly exit from a program 
(see SectionlLlX 

• Extended comparisons (see Section 5.1.5X 

• Scan function. Replaced by scaneq and scanne (see Section 11.8). 

• Str function. 

• Bit-wise boolean operations 

• Segment keyword for procechjres and fmctions. Use the $S command 
instead (see Section 12.1). 

• The following compiler commands (see Section 12.1> 

• SI* and ^- (no automatic I/O checking; program must use ioiesiat 
function) 

• $G ($G+ Is the assumption on the Lisa) 

• IN and IR (for resident code segments) 
•IP 

•IQ 

• SB* and IS** for swapping 

• HJ* and m- (for User Program) 

•IV 

In general, do not assume that a connpiler command used in Apple II or 
/^pple III Pascal is valid on the Lisa Furthermore, do not assume that an 
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Apple II or Apple III Pascal compiler command Is "harmless" on the Llsa^ as 
It may be implemented with a different meaning. 

A.3 Other Differences 

The following features of Pascal on the Lisa are different from the 
corresponding features of Apple 11 and Apple III Pascal: 

• Size of all strings must be explicitly declared (see Section 3.1.1.6). 

• Mod and dlv~Pascal on the Lisa truncates toward (see Section 5.1.2). 

" Apple II and Apple III Pascal ignore underscores; Pascal on the Lisa does 
not They are legal characters In Identifiers (see Section 1.2). 

• A goto-statement cannot refer to a case-constant in Pascal on the Lisa 
(see Section 6.1.3). 

• A program must begin with the word program in Pascal on the Lisa (see 
Chapter 8). 

• Trunc is different (see Section 11.3.1). 

• wnte(b) where b is a boolean will write either ' true* or 'FALSE* in Pascal 
on the Lisa (see Section 10.3.3> 

• Whether a file is a textfile does not depend on whether its name ends with 
".TEXT" when it is created. Instead^ any external file opened with a file 
variable of type text is treated as a textfile^ while a file opened with a 
file variable of type file of char is not; it is treated as a "datafile/ i.e. a 
straight file of records which are of type char (see Sections 3.2.4 and 10.2). 

• Get put^ and the contents of the file buffer variable are not supported on 
files of type text Use only the text-oriented I/O procedures with textflles. 

• Eoln and eof functions on files of type text work as they do on interactive 
files in Apple II and Apple III Pascal. 

• Pascal on the Lisa does not let you pass an element of a packed variable as 
a variable parameter (see Sections 7.3.2^ 11.7, and 11.8). 

• Limits on sets are different (see Section 3.2.3). 

• The control variable of a for-statement must be a local variable (see 
SecUon 6.2.3.3)1 

• In a write or writeln call, the default field lengths for integer and real 
values are 8 and 12 respectively (see Section 10.3.3). 
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This appendix describes the known anomalies in the current implementation of 
the compiler. 

B.1 Scope of Oeclaied Constants 

Consider the following program: 

program cscopel; 
const ten=10; 

procedure p; 
const ten=ten; {WIS SHOULD BE AN ERROR} 
begin 

writeln(ten) 
end; 

begin 

P 
end. 

The constant declaration in procedure p should cause a compiler error, becewse 
It is illegal to use an identifier within its own declaration (except for pointer 
identifiers). However, the error is not detected by the corrpiler. The effect is 
that the value of the global constant ten is used in defining the local constant 
terv and the writeln statement writes "10". 

A more serious aiomaly of the same kind is illustrated by the following 
program: 

program cscope2/ 
const red=l; violet=Z; 

procedure q; 
type arrayType=array[red.. violet] of integers- 
color = (violet^ blue, green, yellom, orange, red); 
var arraj^arrarrayType; c: color; 
begin 
arrayVar[l]:=l; 
C:=red; 

»riteln(ord(c)) 
end; 

begin 

q 

end. 
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Within tlie procedure q, the global constants red and violet are used to define 
an array index type; the effect of arFa)(redL.violet] is equivalent to arTa){l^]. 
In the declaration of the type color, the constants red and violet are locally 
redefined; they are no longer equal to 1 and 2 respectively— irotead they are 
constants of type color with ordinalities 5 and respectively. The writeln 
statement writes "5". 

The use of red in the declaration of the type color should cattjse a compiler 
error txit does not 

Consider the statement 

arrayVar[l]:=l; 
If this statement is replaced by 

arrayVar [red] : =1; 

a compiler error will result, as red is now an illegal index value for arrayVar 
--even though arrayVar is of type array Type and array Type is defined by 
anray[red^violet]. 

To avoid this kind of situaticn, avoid redefinitioi of constant-identifiers in 
enumerated scalar tyf«s. 

Bl2 Scope of Base-Types for Pointers 

Consider the following program: 

prograro pscopel; 

type s=0..7; 

procedure nekecurrent; 
type sptr=*s; 
s=record 
ch-.char; 
txx)l:tioolean 
end; 
var current :s; 
ptrs:sptr; 
begin 
ne«(gtrs); 
ptrs :=current 
end; 

begin 

iBkecurrent 
end. 

Here we have a global type z, which is a subrange of integer; we also have a 
local type s, which is a record-type. Within the procedure makecurxent^ the 
type sptr is defined as a pointer to a varisri3le of type s. The intention is that 
this should refer to the local type s, defined on the next line of the program; 
unfortunately, tiowever, the compiler does not yet know atKxit the local type s 
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and uses tlie global type s. Thus plre becomes a pointer to a variable of type 
tL7 instead of a pointer to a record. Consequently the statement 

ptrs* := current 

causes a compiler error since ptn' and current are of incompatible types. 

To avoid this kind of situation, re-declare the type s locally before declaring 
the pointer-type sptr based cm s. Alternately, avoid re-declaration of 
identifien that are used as base-types for pointer- types. 
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C-l Tokens and Constants C-1 

02 Blocks C-4 

C3 Data Types C-5 

CA variables C-9 

C.5 Expressions C-10 

a6 Statements C-12 

C.7 Procedures and Functions C-15 

C.8 Programs C-16 

as Units 0-17 



Syntax of the Language 



This appendix collects the syntax diagrams found In the main sections of this 
manual. See the Preface for an Introduction to syntax diagrams. 

C.1 Tokens and Constants (see cnapter l) 



JettBr 



(a) tfmxjgn (z) , (a) mivugn (z) 



^s^^ » 



® through 



hex-digit 



X H t^iglt I j-^ 



identifier 



> letter 



letter 



digit 4 



_> 



underscore 



digit-sequence 



digit 



rrs^LT^ 



hex-digit-seouence 



Z 



hex-digit 



T^ 
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Syntax- 



unsloned-Jntecier 



-r — » j digit-; 



digit-sec^ence 



hex-digit-sequence 



j^ 



sign 



•0 




ijnsJgneiJ-/ea/ 

— » digit-sequence ""^^yy-^ digit-sequence 



T 



1, j ^ 

— ^i>^ <:r;fllp-fantftr -^ 



scale-factor 



<E> 




Sign 



TT 



digit-sequence 



iMislgnea-numper 



TD 



unsigned-integer 



unsigned-real 



signecl-number 



^> sign -^ 



unsigned-number 



quoted-strfng-constant 



*<>T1 



string-Character 



^ 



O- 
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Syntax 



string-character 



-\ 



any char except (jj ctrCR 



€^-K> 



r^ 



quotea-cnaraoter-constant ^(Ty ^ string-character h -»0-» 



constant-declaration 



identifier 



constant 



HO-^ 



constant 



"Y 



\^ l/ 

^^ sian -^ 



constant-Identifier 



'^^ slgned-mimber 
^^ quoted-string ■ 
^ quoteo-cnar — 



^ 
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Syntax 



02 Blocks (see Chapter 2) 

oicx^ 



_ — ^ 



^ constant-cteclaration-part 



""^ type-declaration-part 



label-declaration-part 



D 



O 



O 



^^ variable-declaration-part 



-^ 



D 



^ procedure-axl-functicn-declaration-part 



^ 



n 



^ statement-part 



lai)el-cfeclaratJon-part 

Ki^) 



z 



label 




<i> 



/ace/ 



^ digit-sequence 



coKtant-declaiatlon-part 
— K^^} 



I 



constant-declaration 



T 



ty/oe-cfeclaiatiai-part 
» (type> 



^ 



type-declaration 



T^ 
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Syntax 



[/ariable-cteclaraUon-part 



I 



variable-declaration 



T^ 



procedure-and-function-declaration-part 



12 



procedure-declaration 



function-declaration 



statement-part ^ 



compound-statement 



C3 Data Types (see Chapter 3) 



tvpe-declaratJon 



identifier 



»0— ^ type] — »Q— ► 



type 








-V 




^ 






*"— > structured-type 








V ^ 




w poinujr type ■ 




^ 



simple-type 












"S 




^ 














> 








^ fc 






^-i> sinng-type - 







real-type ^i real-type-identifier 
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Syntax 



orainal-type 




*- 


subrange-type 












N ^ 






-\ 








^^ 


enumerated-type 










> 






ordinal-type-ideniifler 


N ta 











String-type 

— ^ — » ( string ) -->(J)— » fsize-attrlt)ute"] — »(T)-Y ► 



string-type-identlfier 



J 



size-attrJtHJte 



^ unsigned-integer 



enumeratea-type ^ (J^^ identifier-list |-»(j>-» 



identifier-list 



j ^ identifier [ -^ 

^ — Q^ 



sa,rsn,^-type ^ r ^^;^;Sl 



constant 
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Syntax 



structuieci-type 



"Y^ j^ — ► 



array- type 



T 



set-type 



file-type 



record-type 



T 



¥■ Structured-type-identifier 



array-type 



-»( ^array} -»([)-^ ^ index-type~[ -^r^(y)--»(or)-» f type 



O 



jnt»x-tfpe ^1 ordinal-type"] ►■ 



J^^c±im-*(^^ 



V, J 

^ field-list — ^ 



►(end}-»- 



fleia-iist 



~\ 



fixed-part 




variant-part 




fixed-part 



I 



field-declaration 



<£> 



J 



field-declaration 



*► ictentifier-list 



type 
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Syntax 



vartant-part 



•xr 7-> tag-field-type ■^\S)-y# variant ^d^ 

^ ldentifler} »(Ty ^^^ Q)^ 



tacj-fJeld-type 



oitiinal-type-identifier 



variant 



^ constant f -yXTX O \ — r^(Sy-^ 

V n \ ^ J ^M field-list K 



o 



^^~^yP^ — ►(ler)-»(^or)-» | ordinal-type 






^y/7/^-^^ ■ »0-> | base-type' 

pointer-type-identifier 



t: 



rr^ 



&3se-tiipe ^ type-ldenUfier I ► 
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Syntax 



CA Variables (see Chapter 4) 



varlaOle-aeclaration 



identifier-list ->Qy-^ type -^(7) ► 



varid^le-reference 

► 



variable-Identifier 



^^ qualifier #-^ 



vari^le-identifier 



^ ictentifier 



qualifier 



^ 



index 



field-designator 



^ 



file-buffer-symbol 



^ pointer-object-symbol 



Vw. 



index 



<!> 



I 



expression 



O- 



T 



0)— 



fleia-aeskf^tor »Q— » | laentlfler 



file-txjffier-symbol 



O 



pointer-obfect-symtxjl 



•O 
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Syntax 



as E)9>resslons (see cnapter 5) 

msigned-constait 



"T 



^^ 



^ 



wisigned-number 



quoted-strlng-constanl 



■> 



constant-identifier 



<my 



factor 












•\. 




■\ 






MfX 












w Uf iSiyricCi uonsi^ii 


> 












w Tunciion Call 


-V 














> 






^ *vO~^ expression >(J) 








\ b 












slmpJe-expiessJon 



^sion W 



^ term 



"^ 



O— H 



^ — ©* — 
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Syntax 



expression 



simple-expression 






simple-expression 



nwicUon-caii 

^ 



function-identifier 



^ 



actual-parameler-list 



zr 



actuai-parameter-nst 



<(> 



<S> 



^\\/~r — > i actual-parameter { — «r — ^xV) — ► 

^ o* ^ 



actual-parameter 




k>. 


expression 














"V 


^>-* 




•\ 


^ 






variable-reference 








^ 


















^-^ 


procedure-identifier 


> 








^ ^ 












^ 


runcuon-ioe 


1 l^iliCi 











set-constructor 



<i> 



X 



C 



member-group 



O 



J 



:r^ 
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Syntax 



mentjer-QWUD 



expression 



^-»(V)-» expression -^ 



C^ statements (see cnapter 6) 

statement 



"W 



label Y ^Qy^ r^ 



T 



simple-statement 



structured-statement 



^ 



latjel 



^ digit-sequence 



slrwle-statement 



T 



assignment-statement 



assignment-statement 



procedure-statement 



goto-statement 



^^— ^ 



T2 



vari^le-reference 



function-Identifier 



»(^ — » expression 



pnxeOure-statement 

► 



procecfejre-identifier 



T^i 



actual-parameter-list 



TT 



goto-statement ^ (^^^y^S;^^ 



C-12 



Pascal Reference Manual 



Syntax 



structured-statement 




^ 












\ 


^ 
^ 


conipouncj" s (.oici i ici 1 1. ~ 




. 






conditional-statement 






repetitive-statement 






^ 






with-statement 








" 








w 



conrpound-statement 
Ktegln> 



7— » | statement | — ^ 



<^ 



O 



concfUJonal-statenient 



u 



if-statement 



case-statement 



su 



If-statement 



{!£)—•► expression 



W(^then 



D 



>H 



statement 



^'-►(else^-^ statement -^ 



case-st3tenfrent 



(ca5e^-» expression 




-KiK 



Otherwise-Clause 



>(enid)-» 



£»»P 



Y^ constant --«r KZ)~^ statanent 

\ TN- ) 



O 



otherwise-clause 



-»(7)-» Cotfierwise ^ -^ statement 
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Syntax 



repeUUve-stat&mnt 



-\ 



repeat-statement 



wniie-statement 



^ for-statement 



k. 



repeat-statement. 



>( repeat ^7-^1 statement -r — ►(until) — ► 

Kj—T^rl) — 



e)(pression 



O 



while-staterwnt 



•» ( while) — ► expression 



statement 



for-statement 

►(for)-» cmtrol-variable ~^\^y-^ initial-value 



C 



D 



(to) j^ final-value ->(*)-► statement 






control -variable 



► variable-identifier ► 



initial-value 



expression 



final-value 



► expressim ► 



wlth-statement 



-*(^yj* 



record-variable-reference 



o 



T 



KgH^ 



statement 
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Syntax 



C.7 Procedures and Functions (see Chapter 7) 

pwcettJte-declaiaUon 

procedure-heading ■>(7)> procedure-body >(T) — ► 



procedure-txxty 



"T 



block 



"" » (^ forward) — > 

external) ^ 



pwceduie-heactlng 

»(procedLge) — ► identifier 



^ 



formal-parameter-list 



zr 



ftjnction-aeclaration 

function-heading -^(T)-^ function-body -^Q) — ► 



function-lxtcly 



"T 



block 



^^^ » ( forward) — > 

— » ( external) ^ 



/2/^^;a7-/^afly/y » ( ^i;^5^;;> > n5^;^5?i;; 



c 



D 



Xi 



formal-paremeter-list 



/"'"^Vy^ result-type 



result-type 



^ ordlnal-type-ldentlfler 



^ 



real-type-identifier 



^ 



pointer-type-identlfier 
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Syntax 



formal -parametar-JJst. 



parameter-declaration 



7 — ^ 



''-^ procecfcjre-heading 



-> 



^ function-heading 



<^ 



<))— 



oarameter-cfeciaraUon ^ 



IdenUfier-llst 



-»(T)-» | type-ldenUfleT 



C^ Programs (see Chapter 8) 

pwgram 

program-heading f -^Ty 



^ uses-clause >(7)-^ 



blcx:^ 



pingram-neaaing 



— Kprogra^i)'^ 



IdenUfier 



V(X 



program-parameters 



KE^' 



, amya7>Ta3/awfe«r ^i laenuner-Ust 



uses-Clause 



» ( uses ) - 



ictentifier-list 
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Syntax 



C.9 UWts (see cnapter 9) 

regular-unit 



unit 



it-heading — KT) 



J 



^ Interface-part -» Implementation-part -»( end} -»(V) — ► 



unlt-headinq ^f^TV^Jd^Urt^ 



interfaoe-pait ^ ( j^^^^^^^^y 



J 



"•*♦ uses-clause 



^ 
^ 



D 



constant-declaratlon-part 



D 



"■*♦ type-declaration-part 



^ 



D 



variadle-declaratlon-part 



<~ 



D 



^ procedure-and-funcUon-declaration-part 



Jnp/emenlat/on-part ^ ( - tnyiarentaUocT )- 



J 



r 



^^ type-declaratlon-part 



^ constant-declaration-part 



b 



^ 



b 



*"^ variable-cteclaration-part 



<~ 



b 



^ procedure-and-function-declaratlon-part 



^— ^ 
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Floating-Point Arithmetic 



D.1 Introduction 

Floating-point arithmetic in Pascal on the Lisa (all arithmetic involving real 
values) confom^ to most of the single-precision aspects of the IEEE's Proposed 
Standara for Binary Floadng-Point Arithmetic (Draft 10.0 of IEEE Task P75a)L 

IEEE Standard arithmetic provides better accuracy than many other floating- 
point implementations. It also reduces the problems of overflow^ underflow, 
limited precision, and invalid operations by providing useful ways of dealing 
with them. 

The FPLIB library unit (in the file lOSFPLIB) contains the routines that perform 
floating-point arithmetic (including all the transcendental functions and the 
sept function). FPLIB must be linked into ^y program that uses floating-point 
arithmetic; however, it is not necessary to explicitly refer to FPLIB in a uses 
clause unless the progr^n calls the specialized support procedures and 
fLffictions declared in the interface of FPLIB. 

This maiual assumes that you do not explicitly use the FPLIB tnit, and that 
therefore only the default options of IEEE arithmetic are applicable. 

As a general rule, you can write Lisa Pascal programs that use floating-point 
arithmetic without worrying about the differences between IEEE Standard 
arithmetic and other floating-point implementations. 

The following points apply if your program writes out floating-point numbers as 
textual representations (via write or wiitein): 

• Anything in the output that looks like a number will be correct (and 
possibly more accurate than under other implementationsX 

• If your output contains a string of two or more pluses or minuses, this 
indicates a value of «», resulting from division by zero or some other 
operation that caused a floating-point overflow. 

• If your outfxit contains the string "NaN" (meaning Not a Number), this 
indicates the result of some invalid operation that would probably have 
caused a program halt or a wrong output uncter other implementations. 
Note that any real value in text output that does not include the string 
"NaN" is guaranteed not to have been affected by any invalid operatloa 

D.2 Rouncfing of Real Results 

When a real result must be rounded, it is always rounded to the nearest 
representable le^ value. If the unrounded result is exactly halfway between 
two representable real values, it is rounded to the value that has a zero in the 
least significant digit of its binary fraction (the "even" value). 
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Q3 /Nccuracy of /Niitrmetic Gperations 

The arithmetic operations ^ -, *, I, rounds tiunc^ and sqrt are accurate to 
within half a unit in the last bit. Remainders are computed without rounding 
error. 

D.4 Q/erflow and Division by Zero: Infinite Values 

The result of floating-point overflow is either « or -». These are values of 
type real that c^ be used in further calculations aaid follow the mathematical 
conventions: for example^ a finite nunber divided by «» yields zero. 

Dividing a finite non-zero value by zero also yields «» or -«» (m floating-point 
arithmetic). 

Infinite values have textual representations that can be read by read or readln 
or written out by write or writeln. 

Tables D-1 and D-2 below show the results of arithmetic operations on 
infinities. Note that any operation involving a NaN as an operand produces a 
NaN as the result 



Table D-1 
Results of /Vddition and subtraction on Infinities 



Left 



Right 
cperana 



Cfjerana 




-00 


finite 


♦00 


-00 

finite 

♦00 


+ 


—00 
-00 

NaN 


-OB 

finitef 

♦00 


NaN 

♦00 
♦00 


-co 

finite 

♦OB 


- 


NaN 

♦00 
♦00 


-oo 

finitet 

♦OB 


-co 

—00 

NaN 


f Result is an infinity If the operation overflows. 
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Table D-2 
Results of Multiplication and Division on Infinities 

Right 
Cperanci 



Left 

Operand 




±0 


finite 


^M 


±0 
finite 

♦00 


H 


±0 
±0 

NaN 


±0 
finitef 

too 


NaN 

fOO 
♦00 


±0 
finite 

♦CD 


/ 


NaN 

4; 00 
♦00 


finitef 

too 


±0 
±0 

NaN 


t Result is an infinity if Uie operation overflows. 


A*7/fe'Sign of result is determined by the usual matbemaUcal rules. 



D5 Invalid Gperatlons: NaN Values 

An invalid operation (such as dividing zero by zero) does not cause a halt 
Instead it returns a special diagnostic value^ and execution continues. The 
result of an invalid operation is called a AfesV which stands for Tvtot a 
Number." 

A NaN resulting from an invalid operation is a propagating NaN This means 
that if the NaN is used as an operand in another oi9eration^ the result of the 
operation will be the same NaN. NaNs can be written out via write or wrlteln 
and read via read or leadln; the textual representation is "NaN" (optionally 
followed by a quoted string). 

The following operations are invalid and return a NaN value: 

• oo-oa Qf oa.*/-oo) 

• »* jKOO 

•0/0 

• t^/to' 

• The Hn, cos^ In, and sqrt functions, when the arguments are inappropriate. 

(See the funcUon descriptions in sections ll.ft.ft, ll.ft.5, 11.4.7, and 11.4.8, 
respectively.) 
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06 Integer Convenlon Overflow 

Integer conversion overflow can occur In tanc or round (see Chapter 11) If the 
actual-parameter exceeds the txxjnds of the predeclared type integer. The 
result returned is unspecified. 

D.7 Text-Oriented I/O Conversions 

The read^ readUv write^ and wrlteln procedures require the conversion of 
numbers from decimal to binary on input and from binary to decimal on output. 
The error in these conversions Is less than 1 unit of the result's least 
significant digit (In the past^ base conversions have rarely been done 
accurately in a way that permits simple error bounds to be put on the results.) 

Real values appear as character strings in two different contexts: as source 
code processed by the compiler (real constants), and in text files written and 
read by Pascal programs. The signed-number syntax of Chapter 1 applies In 
both cases. However^ the Compiler does not accept infinities and NaNs. 

For read and write, *«> is represented by a string of at least two plus signs, 
and -« by a string of at least two minus signs. NaNs are represented by the 
characters "NaN", with an optional leading sign, and an optional trailing quoted 
string of characters; an example is 

-NaN'12:34' 

The character string is sometimes used to provide diagnostic data 

D.8 FPLIB Interface 

IMPLEMENTATION NOTE 

The IEEE numerics are a proposed standard, and this implementation 
may be redesigned for future releases. 
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UNIT fpllb ; INTRINSIC ; 



{ Use this header for intrinsic 
library. } 



{ FPLIB floating point library version A53, 29 March 1983 } 
{ Copyright 1983, Apple Cooputer Inc. } 



{$setc fp_foros 



:= true } 



{$setc fp_testversion := false } 
{$setc fp_conipllersubset := false } 



INTERFACE 



{ True to compile for OS, false for 

Monitor. } 
{ True if special test library. } 
{ True to cofflpile special subset 
library for Pascal compiler, 
false to conpile full library. } 



{- — 
CONST 



{ CONSTANTS to parameterize floating point types } 



maxfpstring = 80 ; { Declared length of floating point string type, } 
maxfpreg « 1 ; { Floating point registers are numbered 0..maxfpreg } 

{ CONSTANTS for random number generation } 

randmodulus = 2147483647 ; { Prime modulus for random nuiJber generator. } 

{ CONSTANTS for NaN Error Codes } 

Invalid Square Root such as sqrt(-l). } 
Invalid Addition such as +INF - ♦INF. } 
Invalid Conversion to Integer. } 
Invalid division such as 0/0. } 
Trapping NaN encountered. } 
Ordered compare of unordered quantities. } 
Invalid use of Infinity in Projective Mode. } 
Invalid Multiply such as * INF. } 
Invalid Remainder or Modulo such as x REM 0. } 
Invalid binary to ascii conversion parameter. } 
Attempt to promote single denorm to double. } 
Attempt to convert nonnormal to single or double. } 
Attempt to convert invalid ASCII string. } 
Attempt to convert NaN 'invalid string'. } 
Attempt to convert unrepresentable ASCII string. } 
Attempt to convert NaN valued integer to floating } 



nansqrt 


= 1 . 




nanadd 


= 2, 




nanint 


- 3, 




nandiv 


= 4, 




nantrap 


- 5, 




nanunord 


= 6, 


■ 


nanproj 


- 7 , 




nanmul 


= 8, 


• 


nanrem 


- 9, 


■ 


nanascout 


= 10, 


. 


nanpromote 


- 11 . 


■ 


nanresult 


= 12, 


\ 


nanascbin 


« 17, 




nanascnan 


= 18, 


. 


nanascin 


- 19, 




naninteger 


= 20, 


. 
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nanzero 

nantrig 

naninvtrig 

nanexp 

nanlog 

nanpower 

nanflnan 

naninlt 



21 . 
33, 
34. 
35. 

36 , 

37 . 

38 . 
255 



Attempt to create a NaN with zero slgnlficand. 
Invalid argument to trig routine. } 
Invalid argument to Inverse trig routine. } 
Invalid argument to D"x for constant b. } 
Invalid argument to log routine. } 
Invalid argument to x*l or x*y routine. } 
Invalid argument to financial function. } 
uninitialized storage. } 



{ — 
TYPE 



■> 



{ TYPES tnat are subranges } 



fp_reglndex » 0..maxfpreg ; { Index In floating point register array. } 

nibble = 0,.15 ; { Hex "digit". } 

fp_bcdlndex = 0..27 ; { Index In bcdstrlng type. } 

fp_6blt = 0..63 ; { For six bit fields. } 

byt = 0..255 ; { Unsigned byte. } 

bite = -128..*127; { Signed byte. } 

{ TYPES that are packed arrays } 

fourblte = packed array [0..3] of bite ; 
elghtblte = packed array [0..7] of bite ; 
tenblte = packed array [0. .9] of bite ; 

{ TYPES that represent numbers^ Infinities, and NaNs } 



fp_blte = 
f p_int6A = 
fp_double = 
f p_extended = 



bite ; 
elghtblte ; 
elghtblte ; 
tenblte ; 



{ 64 bit Integer with -2 "63 as NaN. } 
{ IEEE double precision floating point. } 
{ IEEE double extended floating point. } 



fp_reglster - packed record { Floating point register. } 

sign : bite ; { for positive, -128 for negative } 

tag : bite ; { l=normal,2»zero,4=lnf,8=NaN^16=nonnorroal } 

exponent : Integer ; 

fraction : elghtblte ; { actually slgnlficand } 

end ; 

fp_bcdstrlng = packed array [fp_bcdlndex] of nibble ; { packed bed string } 
fp_strlng = strlng[maxfpstrlng] ; { String parameter. } 
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fp_type = ( tfp_blte, tfp_lnteger, tfp_longlnt, tfp_lnt64, 
tfp_real^ tfp double, tfp extended, tfp_register, 
tfp_l)cdstrlng7 tfp_strlng ) ; { Names for nuntoer types } 

{ TYPES that point } 

pfp_Dlte = " fp_Dlte ; 

pfp_lnteger = * integer ; 

pfp_longint = " longint ; 

pf p_int64 « " fp_int64 ; 

pfp_real = " real ; 

pfp_double = ^ fp_double ; 

pf p_extended = " f p_extended ; 

pfp_register = * fp_register ; 

pfp_bcdstring = " fp_txxlstring ; 

pfp_string = " fp_string ; 

fp_pointer = " integer ; { Free pointer to any type. } 

fp_procaddress« fpjwlnter ; { Actually * procedure with no arguments. } 

{ TYPES that provide non-numeric types for floating point use } 

xcpn = ( invop, overfl, underfl, divO, inxact, cvtovfl, fp_xcpn6, fp_xcpn7); 
{ Floating point exceptions: 

invop.-inxact are the IEEE exceptions 

ctvovf 1 is for floating to integer conversion overflow 

fp_xcpn6 and 7 are for future expansion } 

excepset = set of xcpn ; { For handling all exceptions at once. } 

roundtype = (rnear, rzero, rpos, rneg, rout) ; { Rounding modes. } 

fp_cc = (equal, lesser, greater, unord) ; { Results of conparisons. } 

fp_kindtype = ( zero, nonnormal, norml, inf, NaN) ; { Floating operands. } 

f p_f ormat = 

( fp.lisa, fp_free, fp_iround, fp_i, fp_f, fp_el, fp_e2, fp_e3, 

fp_e4, f p_e ) ; 

{ Output formats for binary to ascil routines. } 

{ TYPES that provide IEEE arithmetic modes } 

rmode = rnear .. rneg ; { IEEE rounding modes. } 

closure = ( pro J, affine ) ; { IEEE infinity modes. } 

denorm = ( warning, normalizing ) ; { IEEE denormalized modes. } 

extprec = ( xprec, spree, dprec ) ; { IEEE rounding precision modes. } 
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{ TYPES that define floating point trapping } 

f p_traprecorcl = record { of Information for oonposlte floating point trap } 
header : Integer ; 

{ <0 for atomic floating point operation from F-llne op code 
=0 for composite floating point operation 
>0 for atomic Pascal Real arithmetic operation } 
es : excepset ; { Exceptions that occurred in this operation. } 
procname : pfp_strlng ; { procname" contains name of procedure } 
optypel, optypeZ^ resulttype : fp_type ; { Operand and Result types } 
opl, op2, result : fpjwinter ; { Operand and Result pointers > 
end ; 

pfptraprecord = * fp_traprecord ; 

{ TYPES that define the FLOATING POINT CONTROL BLOCK, FPCB_ } 

fp_statustype = packed record { Non-numeric floating point status } 
condition : bite ; { contains invalid code and fp_cc } 
excep : bite ; { Sticky exception-occurred bits for each xcpn } 
tmode : bite ; { Scratch } 

texcep : bite ; { Last-operation exception-occurred bits } 
mode : bite ; { Bit for each IEEE mode > 
trap : bite ; { Trap-enabled bits for each xcpn. } 
Instad : pfp_traprecord ; { fp_traprecord or last F-line op code } 
end ; 

fp_regarray » array [fp_reglndex] of fp_reglster ; 

fp_blocktype = record { Floating point status and numeric registers } 
status : fp_statustype ; 

f : fp_regarray ; { FPCB_.BLOCK.F[i] Is "FPl" in comments. } 
end ; 

fpcb_type = packed record { Floating point control block. } 
case boolean of 
false :( { current definition } 

ptrapvector : array [xcpn] of fpj)rocaddress ; 

{ Pascal language floating point trap vector. } 
block : fp_blocktype ; 

) ; 
true : ( { obsolete definition for compatibility } 
trapvector : array [0..7] of " longlnt ; 
condition : bite ; 
excep : bite ; 
tmode : bite ; 
texcep : bite ; 
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end ; 



mode : bite ; 

trap : Dite ; 

Instad : longlnt 

f : fp_regarray ; 

unused : array [xcpn] of fp_procaddress ; 

) ; 



p_f pcD_type = " f pcD_type ; 

{$lfc not fp_testversion } 

{ TYPES for conpatibllity with previous releases } 
intl6 = packed array [0..1] of Dite ; int32 = fourbite ; int64 = fp_int64 
single « fourbite ; double = fp_double ; extended = fp extended ; 
fpreglster = fp_reglster ; fpstrlng = fp_strlng ; condltloncode = fp_cc ; 
fp6bit = fp_6bit ; fpregarray = fp_regarray ; fpkindtype = fp_kindtype ; 
fpcbtype = fpcb_type ; pfpcbtype = p_f pcb_type ; 
{$endc } 



{- 



•} 



VAR { FLOATING POINT CONTROL BLOCK } 

FPCB_ : fpcb_type ; 

{$ifc not fp_conpilersubset > 

( ) 

{ hICROSEGMENT fpmsub } { Internal assentoly language procedures only. } 
{ .. } 



{ MICROSEGMENT f 32SUb } 



function 
function 
function 
function 
function 
function 



f52_ininus ( 
f32 integral ( 
f52_fraction ( 
f32_ilogD ( 
f32_scale ( 
f32_kind ( 



real ) 
real ) 
real ) 
real ) 
real ; 
real ) 



boolean ; 
boolean ; 
real ; 
integer ; 
: integer ) 
fp_kindtype 



{ Sign(x) } 

{ Is X integral? } 

{ Fraction part(x) } 

{ Exponent(x) } 

: real ; { x * 2"i } 



{ Returns Zero, Norml, Inf or NaN; NonNormal classifies as Norml } 

{$endc } 

function f 32_fpcb : p_fpcb_type ; { Returns aFPCB_ } 

{$ifc not fp_corapiler subset } 
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{■ 



{ mCROSEGMENT UXSOSUb } 

{ EXTENDED PRECISION ARITmETIC } 

{ PROCEDURES for monadic zero address arithmetic } 



procedure. fpneg ; { FPO 

procedure fpabs ; { FPO 

procedure fplnt ; { FPO 

procedure fpsqrt ; { FPO 



= -FPO. } 

= abs(FPO). } 

= integral part of FPO } 

« sqrt(FPO) } 



{ PROCEDURES for dyadic zero address arithmetic } 



procedure fpadd ; 
procedure fpsud ; 
procedure fpmul ; 
procedure fpdiv ; 
procedure f prem ; 
function fpcom : 



{ FPO 
{ FPO 
{ FPO 
{ FPO 
{ FPO 
fp_CC 



= FPO ^ FPl } 
= FPO - FPl } 
= FPO * FPl } 
= FPO / FPl } 
= FPO rem FPl } 
{ Returns result of FPO compare FPl. } 



{ PROCEDURES for two address arithmetic } 



function 

function 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 



fplnts ( 
fpsqrts( 
fpnegd ( 
fpabsd ( 
fpintd ( 
fpsqrtd( 
f pnegx ( 
fpabsx ( 
fpintx ( 
fpsqrtx( 



X : 
X : 
var 
var 
var 
var 
var 
var X, 
var X, 
var X/ 



real 
real 



X, 
X, 
X, 
X, 
X, 



: real ; 

: real ; 

fp_dout)le 

fp_double 

fp_doudle 

fp_douDle 

fp_extended 

fp_extended 

fp_extended 

fp_extended 



integral part of x 
sqrt(x) } 



} 



-X } 
abs(x) } 

Integral part of 
sqrt(x) } 
-X } 

abs(x) } 

Integral part of 
sqrt(x) } 



X } 



X } 



{ PROCEDURES for three address arithmetic } 



function fpadds ( x, y : real 

function fpsuDs ( x* y : real 

function fpmuls ( x* y : real 

function fpdlvs ( x, y : real 

function fprems ( x, y : real 

function fpcoms ( x, y : real 

procedure fpaddd ( var x, y> z 

procedure fpsubd ( var x. y^ z 

procedure fpmuld ( var x, y, z 



real ; 
real ; 
real ; 
real ; 
real ; 
fp_cc 



■^ y 
- y 
*y 
/y 

rem 



fp_douDle 
fp_doudle 
fp_double 



{ z := X ♦ y } 
{ z := X - y } 
{ z := X *y > 
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procedure fpdlvd ( var x, y^ z 

procedure f premd ( var \, y, 2 

function fpcomd ( var >c y 

procedure f paddx ( var x, y, z 

procedure f psubx ( var x, y. z 

procedure fpmulx ( var x, y^ z 

procedure fpdivx ( var x, y^ z 

procedure f premx ( var x, y^ z 

function fpcomx ( var x, y 



fp_doudle ] 
fp_doubie ) 
fp_doulDle ) 

fp_extended 
fp_extended 
fp_extended 
fp_extended 
fp_extended 
fp_extended 



{ PROCEDURES for type conversion } 
{ PROCEDURES for FPO := X } 



procedure wnovefp ( x 

procedure inovefp ( x 

procedure smovef p ( x 

procedure dmovefp ( var x 

procedure xmovefp ( var x 



integer 
longint 
real 
fp_douDle 



fp_extended ) 



{ PROCEDURES for FPl := X } 



procedure wnovefpl ( x 

procedure imovefpl ( x 

procedure sinovefpl ( x 

procedure dmovefpi ( var x 

procedure xmovefpl ( var x 



integer 
longint 
real 
fp_douDle 



fp_extended ) 



{ PROCEDURES for Z :- FPO } 



function fpraovew 
function fpnovel 
function fprooves 
procedure fpnoved 
procedure f pmovex 



( var z 
( var z 



integer ; 
longint ; 
real ; 

fp_douDle ) ; 
f p_extended ) 



{ PROCEDURES for Z :- X } 



{ z := x/y } 
{ z : » X rem y } 
f p_cc ; 



{ 
{ 
{ 
{ 
{ 
fp_cc 



■^ y 
- y 
* y 
/y 

rem 



function 

function 

function 

function 

function 

function 

procedure 

procedure 



xmovew 
dmovew 
xmovel 
dmovel 
xmoves 
dmoves 
wnoved 
Imoved 



( var 


X : 


( var 


X : 


( var 


X : 


( var 


X : 


( var 


X : 


( var 


X : 


( 


X : 


( 


X : 



fp_extended 
fp_douDle 
fp_extended 
fp_double 
fp_extended 
fp_double 
integer ; 
longint ; 



integer ; 

integer ; 

longint ; 

longint ; 

real ; 

real 

var z : fp_double 
var z : fp_doudle 
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procedure. smoved ( 


: X 


real 


var 


z : fp_double ) ; 


procedure xmoved < 


' var X 


fp_extended 


; var 


z : fp_double ) ; 


procedure wnovex 


[ X 


integer ; 


var z 


: f p_extended ) ; 


procedure Imovex < 


\ X 


longlnt ; 


var z 


: f p extended ) ; 


procedure smovex ( 


\ X 


real ; 


var z 


: f p_extended ) ; 


procedure dmovex < 


\ var X 


fp_doubl8 ; 


var z 


: f p extended ) ; 



procedure cinovefp ( var b : fp_bodstrlng ) ; 
procedure 164neg ( var x, z : fp_lnt64 ) ; { z := -x } 
function x80_integral( var x : fp_extended ) : boolean ; 
procedure x80_break ( var x, Intx, fracx : fp_extended ; 

var izero^ fzero : boolean ) ; 



{$endc } 
function 



x80_fpcb : p_fpcb_type ; { Returns aFPCB_ } 



{- 



{ mCROSEGMENT Ufpm } 

{ PR(XIEDURES for binary to ascil conversion } 

procedure fp_zero_ascii 

( sign : boolean ; before, after : Integer ; format : fp_f ormat ; 

var s : fp_string ; var error : boolean ) ; 
procedure fp_lnf_ascli ( sign : boolean ; wldtn : integer ; 

var s : fp_string ; var error : boolean ) ; 

{ PROCEDURES for exceptions } 

function getxcpn ( e : xcpn ) : boolean ; 
procedure setxcpn ( e : xcpn ; b : boolean ) ; 
procedure getexcepset ( var es : excepset ) ; 
procedure setexcepset ( es : excepset ) ; 
procedure gettexcepset ( var es : excepset ) ; 
procedure settexcepset ( es : excepset ) ; 
procedure clrexcepset ; 

{ PROCEDURES for trap-enabled bits in FPCB_.BLOCK. STATUS. TRAP } 

procedure gettrapset ( var es : excepset ) ; 
procedure clrtrapset ; { Disables all traps. } 

{ PROCEDURES for floating point trapping } 

procedure fpjjostoperation ( r : fp_traprecord ) ; 

{ Imitates effect of atomic floating point operation by using r.es 
as tne set of exceptions generated by a conposite operation } 
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procedure checktrap ( r : fp_traprecorci ) ; 
{$ifc not fp_conpiler subset } 

I } 

{ mCROSEGMENT UX80 } 

{ PROCEDURES that tell atXXJt FPO } 

function fpminus : boolean ; { FPO has sign bit on? } 

function fpkind : fp_klncltype ; { Returns type of argument In FPO. } 

{ PROCEDURES that tell about extended x } 

function fpminusx ( var x : fp_extended ) : boolean ; { sign bit? } 
function fpkindx ( var x : fp_extended ) : fp_kindtype ; { kind? } 

procedure copysign ( var >c y> z : fp_extended ) ; 

{ z gets y with sign of x. } 
procedure infinity ( var z : fp_extended ) ; { z := +INF. } 
procedure errornan ( error : byt ; var z : fp_extended ) ; 

{ Creates a NaN in z with error code set^ other fields 

zero^ and signals Invop xcpn. } 
procedure createnan ( trap : boolean ; extension : fp_6Dlt ; 

error^ index : byt ; var z : fp_extended ) ; 

{ Creates a NaN in z with 23 significant bits defined. } 
procedure checknan ( var x, z : f p_extended ) ; 

{ z := X but if X is a trapping NaN^ the trapping bit of z is 

turned off and the Invalid flag is set. } 
procedure NaN_parts ( var x : fp_extended ; 

var trap : boolean ; var extension : fp_6blt ; 

var error^ inde)c index2 : byt ; var lowpart : fpjjrocaddress ) ; 

{ Splits up X into its canponent parts, lowpart gets the four 

least significant bytes. } 
procedure choosenan ( var >c y^ z : f p_extended ) ; 

{ X or y must be a NaN. z is set to whichever has the greater 

Error field, z is non trapping. If either x or y is trapping, 

the Invalid flag is set. } 

{ PROCEDURES that act on nuntoers but do not use arithmetic } 

procedure fpswap ; { Exchange FPO and FPl } 

procedure blockprelude ( var fpb : fp_blocktype ) ; 

procedure blockpostlude ( var fpb : fp_blocktype ; var trapcoming : boolean); 

( . . J 
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{ MICROSEGMENT UXSOelem } 

{ PROCEDURES that tell about extended X } 



function ilogb 



( var X : f p_extended ) : Integer ; { exponent of x } 



{ PROCEDURES that produce extended z > 

procedure fpscalex { z :» x * Z*"! } 

( var X : fp_extended ; i : integer ; var z : fp_extended ) ; 

procedure scalb { z := x * 2*y for integral y } 

( var X, y. z : fp_extended ) ; 

{ elementary function PROCEDURES that require initelem } 

procedure exp2 ( var x, z : fp_extended ) ; { z := 2"x } 
procedure exjje ( var x, z : fp_extended ) ; { z := e*x } 
procedure exp2i ( var x, z : fp_extended ) ; { z := 2*x -l } 



procedure log2 ( var x, z 

procedure loge ( var x, z 

procedure logio ( var x, z 

procedure logl2 ( var x, z 



fp_extended ) ; { z := log(x )/log(2) } 

fp_extended ) ; { z := log(x )/log(e) } 

fp_extended ) ; { z := log( x )/log(10) } 

fp_extended ) ; { z :« log2(l*x ) } 



procedure xtoy ( var x, y^ z : fp_extended ) ; { z :» x*y } 

procedure conpound ( var r, p^ z : fp_extended ) ; { z :- (l*r)*p } 
procedure annuity ( var r^ p, z : fp_extended ) ; { z := (1 - (l*rr-p)/r } 

procedure postdyadic( name : fp_string ; var x,y^z : fp_extended ) ; 
procedure xpwry ( var x : fp_extended ; y : Integer ; var z : fp_extended); 
procedure xexpy ( var x, y ^ z : fp_extended ) ; 



{ MICROSEGMENT UX80trig } 

procedure plvalue ( var z 

procedure sinx ( var x, z 

procedure cosx ( var x, z 

procedure tanx ( var x, z 

procedure asin ( var x, z 

procedure acos ( var x. z 

procedure atan ( var x, z 
{$endc} 



{- 



fp_extended ) 
f p_extended ) 
f p_extended ) 
f p_extended ) 
f p_extended ) 
f p_extended ) 
f p_extended ) 



-pi } 
;» sln(x) } 



{ z := arcsin(x) } 
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{ mCROSEGMENT Uf32 } 



Integer): real ; { Does pwrten(n). } 



real ) 


: real 


real ) 


: real 


real ) 


: real 


real ) 


: real 


real ) 


: real 



function f32_pwrten(n 
function f32_exp ( x 
function f32_ln ( x 
function f32_sln ( x 
function f32_cos ( x 
function f32_atan ( x 
procedure f32_trap ; { Floating Point Trapping for Pascal Real Arithnetic } 

( J 

{ mCROSEGMENT f32in } 

{ Simple PROCEDURES to convert ascll to binary } 

function p_f32 ( var s : fp_string ) : real ; 

function f52_r_r ( var f : text ) : real ; { Does reacl(f^real) } 

{ general PROCEDURES to convert ascli to binary } 

procedure read_f32 ( var Inf lie : text ; var Readchars : fp_string ; 

var z : real ; var Error : boolean ) ; { Z^ Readchars get input } 
procedure ascllreal 

( Fileio : boolean ; var Infile : text ; 

var S :fp_string ; Firsts Last : integer ; var Next : integer ; 

var Z : real ; var Error : boolean ) ; 

( } 

{ mCROSEGTCNT f 320Ut } 

{ sinple PROCEDURES to convert binary to ascli } 

procedure f 32_w_e ( var f : text ; x : real ; width : integer ) ; 

{ Does write(f,x: width) } 
procedure f32_w_f ( var f : text ; x : real ; widths after : integer ) ; 

{ Does write(f,x: width .-after) } 
{$ifc not fp_compilersubset } 

{ general PROCEDURES to cofwert binary to ascii } 

procedure f32_nan_ascii ( x : real ; width : integer ; 

var s : fp_string ; var error : boolean ) ; 
procedure f 32_f_ascii ( x : real ; beforepoint : boolean ; after : integer; 

var s : fp_string ; var error : boolean ) ; 
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procedure f32_e_ascll ( x : real ; before, after, ew : integer ; 
var s : fp_string ; var error : boolean ) ; 



{■ 



{ ttlCROSEGMENT X80in } 

{ general PROCEDURES to convert ascil to binary } 

procedure pmovefp ( var S : fp_strlng ; First, Last : integer ; 
var Next : integer ; var Error : boolean ) ; { FPO := S } 

procedure asciimovex ( Fileio : boolean ; var Infile : text ; 

var S : fp_string ; First, Last : integer ; var Next : integer ; 
var X : fp_extended ; var Error : boolean ) ; 



^ 

{ MICROSEGMENT xSOOUt } 

{ general PROCEDURES to convert binary to ascii } 



■} 



procedure x80. 

var s 
procedure x80. 

var s 
procedure x80. 

var s 
procedure x80. 

after 

var s 
procedure x80. 

var s' 
procedure x80 

widtn, 

var s 
procedure x80 

Width," 

var S 



.nan_ascii ( 
: fp_string ; 
i.ascli ( 
: fp_string j 
.ir_ascii ( 
: fp_string , 
f.ascii ( 
: integer ; 
: fp_string , 



var X : f p_extended , 
var error : boolean 
var X : f p_extended . 
y&t error : boolean 
var X : f p_extended , 
var error : boolean 
var X : fp_extended , 



width : integer 



beforepoint : boolean 



var error : boolean 
e_ascii ( var x : fp_extended ; before, after, e« : integer 
: fp_strin(g ; var error : boolean ) ; 
free_ascii ( var x : fp_extended ; 
maxsig : integer ; format : fp_format ; 
: fp string ; var error : boolean ) ; 
ascil ( var X : f p_extended ; 
Before, After : integer ; Format : fp_Format ; 
: fp_string ; var Error : boolean ) ; 



procedure x_ef orm ( var x : f p_extended ; n : integer ; 

var~sigma : integer ; var s : fp_string ; var e : integer ) 
procedure x_iforin ( var x : fp_extended ; 

var Sigma : integer ; var s : fp_string ; var e : integer ) 

{ 
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{ MICROSEGMENT fplldZ } 

{ PROCEDURES that act on nufnbers txjt do not use arithmetic } 



procedure movef p ( var x 
procedure n»vefpl( var x 
procedure f pmove ( var z 
procedure fplmove( var z 



fp_register ) ; { FPO := x } 

fp_register ) ; { FPl :« x } 

fp_reglster ) ; { z := FPO } 

fp_reglster ) ; { z := FPl } 



{ PROCEDURES for 64 bit integers } 



procedure i64abs ( var x, z 

procedure 164mfp ( var x ; 

procedure i6Anifpl ( var x ; 

procedure fpniovel64 ( var z 



: fp_int64 
fp_int64 
fp_int64 
: fp_lnt64 ) 



) ; { z :« abs(x) } 



{ PROCEDURES that produce extended z } 

procedure logh ( var x, z : fp_extended ) ; { z := exponent(x). } 
procedure nextafter ( var x, y^ z : fp_extended ) ; 

{ z gets the next number from x in the direction y^ 
observing current rounding precision mode. } 



{ elementary function PROCEDURES that require initelem } 



procedure 
procedure 

( 
procedure 
procecftjre 
procedure 
procedure 
procedure 
procedure 
procedure 



e value ( 
xtoi 
var X : 
expel ( 
logie ( 
slnhx ( 
coshx ( 
tanhx ( 
abs2x ( 
atan2x( 



var z : fp_extended ) 



fp_extended 



var X, 

var X, 

var X, 

var X/ 

var X, 

var X, 

var X, 



fp. 
fP. 
fp. 
fp. 
fp. 



1 : integer 
extended ) 
extended ) 
extended ) 
extended ) 
extended ) 
f p_extended ) 
f plextended ) 



{ 2 :-e } 
{ z := x^l 



} 



var z : f p_extended ) 
z := expe(x)-l } 
z := loge(l+x ) } 
z := slnh(x) } 
z := cosh(x) } 
z := tanh(x) } 
: { z := abs(x-^iy) } 
: { z := atan(x/y) } 



{ simple PROCEDURES to convert ascii to binary } 



procedure pmoved 
procedure pmovex 



( var s : fp_string ; var x : fp_double ) ; 
( var s : fp_string ; var x : fp_extended ) ; 



{ simple PROCEDURES to convert binary X to ascii S in fp_lisa format } 
{ Comments Indicate logical length of S. } 



procedure dmovep ( var x : fp_double ; var s 
procedure xmovep ( var x : fp_extended ; var s 



fp_string ) ; { 24 } 
fp_string ) ; { 27 } 



D-17 



Pascal Reference Manual Floating-Point Arithmetic 

{ PROCEDURES for use by Basic and other language processors } 

function nextrandom ( lastrandom : longint ) : longint ; 

(* Returns random longint with l <- nextrandom <- randmodulus *) 
procedure x80_nBXf orin ( var x : f p_extended ; 

var Sigma : Integer ; var ^ : fp_strlng ; var e : Integer ) ; 
procedure x80_ef orm ( var x : f p_extended ; 

var Sigma : Integer ; var s : fp_strlng ; var e : Integer ) ; 

{ PROCEDURES for exceptions } 

procedure excepname ( e : xcpn ; var name : fp_strlng ) ; 

{ Returns exception name: after excepname( Invop, name ), 
name = 'Invop' } 
{$endc } 

{ PROCEDURES to get and set IEEE arithmetic modes } 

function getround : rmode ; 
procedure setround ( x : rmode ) ; 
{$lfc not fp_compiiersuDset } 
function getclos : closure ; 
procedure setclos ( x : closure ) ; 
function getdnorm : denorm ; 
procedure setdnorm ( x : denorm ) ; 
function getprec : extprec ; 
procedure setprec ( x : extprec ) ; 

{ PROCEDURES for trap-enaDied bits in fpcb_.block. status. trap } 

function gethalt ( e : xcpn ) : boolean ; 
procedure sethalt ( e : xcpn ; b : boolean ) ; 
procedure settrapset ( es : excepset ) ; 

{ PROCEDURES for Pascal trap handlers in fpcb_.ptrapvector } 

function gettrap ( e : xcpn ) : fpj)rocaddress ; { FPCB_.ptrapvector[e3 > 
procedure settrap ( e : xcpn ; f : fp_procaddress ) ; 
{ FPCB_.ptrapvector[e3 := f } 

{$endc } 

^ ) 
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{ MICROSEGMENT ulnltfp } 

{ FLOATING POINT INITIALIZATION } 

procedure inltfp ; { Initialize the floating point control block FPCB_. } 
{$ifc not fp_conpilersubset } 

procedure inltfptrap ; { initialize maximal floating point trapping. } 
procedure initelem ; { initialize FPCB_ and elementary functions. } 

{ } 

{ PROCEDURES that are noops^ used to load segments } 

procedure Idfpmodes ; { in segment fpmodes } 

procedure idf 32 ; { in segment idf 32 } 

procedure ldx80 ; { in segment x80 } 

procedure idxsoelem ; { in segment xeoelem } 

{ } 

{$endc } 
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E.1 /\txxit inis Appendix 

This appendix describes QuickDraw, a set of graphics procedures, functions, 
and data types that allows a Pascal or assembly-language programmer of Lisa 
to perform highly complex graphic operations very easily and very quickly. It 
covers the graphic concepts behind QuickDraw, as well as the technical 
details of the data types, procedures, and functions you will use In your 
programs. 

We assume that you are familiar with the Lisa workshop Manager, Lisa Pascal, 
and the Lisa Operating System's memory management This graphics package 
Is for programmers, not end users. Although QuickDraw may be used from 
either Pascal or assembly language, all examples are given In their Pascal 
form, to be clear, concise, and more Intuitive; Section E.ll describes the 
details of the assembly-language Interface to QuickDraw. 

The appendix begins with an Introduction to QuickDraw and what you can do 
with It (Section E.2). It then steps back a little and looks at the mathemat- 
ical concepts that form the foundation for QuickDraw: coordinate planes, 
points, and rectangles (Section E.3). once you understand these concepts, read 
on to Section E.4, which describes the graphic entitles based on them—how 
the mathematical world of planes and rectangles is translated into the 
physical phenomena of light and shadow. 

Then comes some discussion of how to use several graphics ports (Section E.6), 
a summary of the basic drawing process (Section E.7X and a discussion of two 
more parts of QuickDraw, pictures and polygons (Section E.8). 

Next, In Section E.9, there's a detailed description of all QuickDraw proce- 
dures and functions, their parameters, calling protocol, effects, side effects, 
and so on—all the technical Information you'll need each time you write a 
program for the Lisa. 

Following these descriptions are sections that will not be of Interest to all 
readers. Special information Is given In Section E.10 for programmen who 
want to customize QuickDraw operations by overriding the standard drawing 
procedures. In Section E.11 for those who will be using QuickDraw from 
assembly language, and in Section E.12 for those Interested in creating 
three-dimensional graphics using the Graf3D unit 

Finally, there are listings of the QuickDraw Interface (Section E.IB), two 
sample programs (Section E.14), and the QDSMpport unit (E.15); and a glossary 
that explains terms that may be unfamiliar to you (Section E.16). 
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E2 PiKkA QuickDraw 

QuickDraw allows you to organize the Lisa screen into a number of individual 
areas. Within each area you can draw many things^ as illustrated in Figure 
E-1. 
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Figure E-l 
Samples of QiBckDraw's Abilities 

You can draw: 

• Text characters in a number of proportionally-spaced fonts, with variations 
that include boldfacing, italicizing, underlining, and outlining. 

• straight lines of any length and width. 

• A variety of shapes, either solid or hollow, including: rectangles, with or 
without rounded comers; full circles and ovals or wiedge-shaped sections; 
and polygons. 

• Any other arbitrary shape or collection of shapes, again either solid or 
hollow. 

• A picture consisting of any combination of the above items, with just a 
single procedure call. 

In addition, QuickDraw has some other abilities that you won't find In many 
other graphics packages. These abilities take care of most of the "house- 
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keeping"— the trivial but time-consuming and botnersome overtiead that's 
necessary to keep things In order. 

• The aJDllity to define meny distinct ports on the screen^ each with its own 
complete drawing environment— Its own coordinate system, drawing 
location, character set, location on the screen, and so on. You ca^ easily 
switch from one such port to another. 

• Full and complete clipping to arbitrary areas, so that drawing will occur 
only where you want It's like a super-duper coloring book that won't let 
you color outside the lines. You don't have to worry about accidentally 
drawing over something else on the screen, or drawing off the screen and 
destroying memory. 

• Off-screen drawing. Anything you can draw on the screen, you can draw 
into an off-screen buffer, so you can prepare an Image for an output 
device without disturbing the screen, or you can prepare a picture and 
move it onto the screen very quickly. 

And QuickDraw lives up to its name! It's very fast. The speed and 
responsiveness of the Lisa user Interface are due primarily to the speed of the 
QuickDraw package. You can do good-quality animation, fast interactive 
graphics, and complex yet speedy text displays using the full features of 
QuickDraw. This means you don't have to bypass the general-purpose 
QuickDraw routines by writing a lot of special routines to Improve speed. 

E.2.1 How To Use QuickDraw 

QuickDraw can be used from either Pascal or MC68000 machine language. It 
has no user Interface of its owa 

If you're using Pascal, you must write a Pascal program that includes the 
proper QuickDraw calls, compile it against the files QD/QulckDraw.CBJ and 
QD/QDSupport.GBJ, link it with the files listed in QO/QDSluff.TEXT, and 
execute the linked object file. 

If you're using machine language, your program should Include the proper 
QuickDraw calls, and .INCLUDE the file QD/GRAFTYPES.TEXT. Assemble the 
program, link It with the files listed In QOA^DStuff.TEXT, and execute the 
linked object file. 

A programming model, QDSample, is included with the workshop software in 
the file QD/QDSampie.TEXT (listed in section E.14.1); it shows the structure of 
a properly organized QuickDraw program. What's best for beginners is to read 
throu^ the text, and, using the superstructure of the program as a "shell", 
modify it to suit your own purposes, once you get the hang of writing 
programs inside the presupplied shell, you can work on changing the shell 
Itself. 

Note that all files related to QuickDraw are prefixed by "QD/". 

QuickDraw Includes only the graphics and utility procedures and functions 
you'll need to create graphics on the screen. Procedures for dealing with the 
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mouse, cursors, keyboard, and screen settings, as well as those allowing you to 
generate sounds and read and set clocks and dates, are described In /^Jpendix 
F, Hardware interface. 

E.Z2 QuickDraw Data Types 

QuickDraw defines three general data types, QDByte, QDPtr, and QDHandle: 

type Qoeyte = -128.. 127 
QOPtr = *QOByte 
QOHandle = "QOPtr 

other data types are described throughout this appendix In the sections In 
which they're relevant For a summary of all QuickDraw data types, see 
Section E.13.2. 

E.3 TTie Mathematical Foundation of QuickDraw 

To create graphics that are both precise and pretty requires not super-charged 
features but a firm mathematical foundation for the features you have. If the 
mathematics that underlie a graphics package are Imprecise or fuzzy, the 
graphics will be, too. QuickDraw defines some clear mathematical constructs 
that are widely used in its procedures, functions, and data types: the coorai- 
nate plane, the point, the rectangle, and the region 

E3.1 TTie Coordinate Plane 

All Information about location, placement, or movement that you give to 
QuickDraw Is In terms of coordinates on a plane. The coordinate plane Is a 
two-dimensional grid, as illustrated in Figure E-2. 
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Figure E-2 
The Cc»idinate Plane 
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There are two distinctive features of the QuickDraw coordinate plane: 

• All grid coordinates are Integers. 

• All grid lines are infinitely thin. 

These concepts are important! First, they mean that the QuickDraw plane is 
finite, not infinite (although it's very large). Horizontal coordinates range 
from -32768 to ♦32767^ and vertical coordinates have the same range. 

Second, they mean that all elements represented on the coordinate plane are 
mathematically pure. Mathematical calculations using integer arithmetic will 
produce intuitively correct results, if you keep in mind that grid lines are 
infinitely thin, you'll never have "endpoint paranoia"— the confusion that 
results from not knowing whether that last dot is Included in the line. 

E3.2 Points 

On the coordinate plane are 4^94,%7,2% unique points. Each point is at the 
intersection of a horizontal grid line and a vertical grid line. As the grid lines 
are Infinitely thin, a point Is infinitely small. Of course there are more points 
on this grid than there are dots on the Lisa screen: when using QuickDraw you 
associate small parts of the gild with areas on the screen, so that you aren't 
bound Into an arbitrary, limited coordinate system. 

The coordinate origin (0,0) Is In the middle of the grid. Horizontal coordinates 
Increase as you move from left to right, and vertical coordinates Increase as 
you move from top to bottom. This Is the way both a TV screen and a page 
of English text are scanned; from the top left to the bottom right. 

You can store the coordinates of a point In a Pascal variable whose type Is 
defined by QuickDraw. The type Point Is a record of two Integers, and has 
the following structure: 

type VHSelect = (V^H); 

Point = record case integer of 

0: (V; integer; 
h: integer); 

1: (vh: array [VHSelect] of integer) 

end; 

The variant part allows you to access the vertical and horizontal components 
of a point either Individually or as an array. For example. If the variable 
goodPt were cteclared to be of type Point, the following would all refer to the 
coordinate parts of the point: 

goodPt.v goodPt.h 

goodPt.vh[V] goodPt.vn[H] 



E-5 



Pascal Reference ManuaJ 



QuickDraw 



E.3.3 Rectangles 

Any two points can define the top left and bottom right corners of a 
rectangle. As these points are Infinitely smalL the herders of the rectangle 
are infinitely thin (see Figure E-3X 
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Figure E-5 
A Rectangle 



Rectangles are used to define active areas on the screen, to assign coordinate 
systems to graphic entities, and to specify the locations and sizes for various 
drawing commands. QuickDraw also allows you to perform many 
fnathematlcal calculations on rectangles—changing their sizes, shifting them 
around, and so on. 

NOTE 

Remember that rectangles, like points, are mathematical concepts that 
have no direct representation on the screea The association between 
these conceptual elements and their physical representations is made by 
a bitmap, described below. 
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The data type for rectangles Is Rect and consists of four Integers or two 
points: 

type Rect = record case Integer of 

0: (top: Integers- 
left: Integer; 
tnttoRi: integer; 
rl^t: integer); 

1: (topLeft: Point; 
dotRight: Point) 

end; 

Again, tJie record variant allows you to access a variable of type Rect eimer 
as four boundary coordinates or as two diagonally opposing comer points. 
Combined with the record variant for points, all of tiie following references to 
the rectangle named DRect are legal: 



bRect 

bRect.topLeft 

bRect. top 
bRect. topLeft.v 
bRect. topLeft.vh[V] 

bRect. bottom 
bRect. botRig^t.v 
bRect. botRight.vn[v] 



bRect .botRl^t 

bRect. left 
bRect. topLeft.h 
bRect. topLeft.vh[H] 

bRect. right 
bRect .botRi^t.h 
bRect. botRlght.vh[H] 

W/\RNING 



{type Rect) 

{type Point} 

{type integer) 
{type integer) 
{type integer) 

(type integer) 
{type integer) 
{type integer) 



If the bottom coordinate of a rectangle Is equal to or less than the top, 
or the right coordinate is equal to or less than the left, the rectangle 
Is an empty rectangle (l.e., one that contains no bits) 

E3.4 Regions 

Unlike most graphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at that), QuickDraw can gather an arbitrary set 
of spatially coherent points into a structure called a region, and perform 
complex yet rapid manipulations and calculations on such structures. This 
remarkable feature not only will make your standard programs simpler and 
faster, but will let you perform operations that would otherwise be nearly 
impossible; it is fundamental to the Lisa user interface. 
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You define a region Dy drawing lines, shapes such as rectangles and ovals, or 
even other regions. The outline of a region should be one or more closed 
loops. A region can be concave or convex, can consist of one area or many 
disjoint areas, and can even have "holes" in the middle. In Figure E-4, the 
region on the left has a hole in the middle, and the region on the right 
consists of two disjoint areas. 




Figure E-4 
Regions 

Because a region can be any art>itrary area or set of areas on the coordinate 
plane. It takes a variable amount of Information to store the outline of a 
region. The data structure for a region, therefore, is a variable-length entity 
with two fixed fields at the beginning, followed by a variable-length data 
field: 

type Region = record 

rgnSize: Integer; 
rgnBBox: Rect; 

{optional region definition data} 
end; 

The rgnslze field contains the size, in bytes, of the region variable. The 
rgnBBox field is a rectangle which completely encloses the region. 

The simplest region is a rectangle. In this case, the rgnBBox field defines the 
entire region,, and there is no optional region data For rectangular regions (or 
err^ty regions), the rgnSIze field contains 10 (two bytes for rgnSize, plus 
eight for rgnBBox). 

The region definition data for nonrectargular regions is stored in a compact 
way which allows for highly efficient access by QuickDraw procedures. 
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As regions are of variable size, they are stored dynamically on tJie heap, and 
the operating System's memory management moves them around as their sizes 
change. Being dynamic, a region can oe accessed only through a pointer; but 
when a region Is moved, all pointers referring to It must be updated. For this 
reason, all regions are accessed through nananes, which point to one master 
pointer which In turn points to the region. 

type RgnPtr = * Region; 
RgnHandle = *RgnPtr; 

When the memory management relocates a region's data In memory, it updates 
only the RgnPlr master pointer to that region. The references through the 
master pointer can find the region's new home, but any references pointing 
directly to the region's previous position In memory would now point at dead 
bits. To access Individual fields of a region, use the region handle and double 
Indirection: 

ii»yRgn**.rgnSize {size of region whose handle Is myRgnJ 

HiyRgn^^.rgnBdox (rectangle enclosing the same region} 

nyRgn**.rgnB8ox.top {minimum vertical coordinate of all points 

in the region} 
inyRgn*.rgnB8ox {semantically incorrect; will not compile if 

myRgn is a rgnHandle} 

Regions are created by a QuickDraw function which allocates space for the 
region, creates a master pointer, and returns a region handle. When you're 
done with a region, you dispose of it with another QuickDraw routine which 
frees up the space used by the region. Only these calls allocate or deallocate 
regions; do not use the Pascal procedure new to create a new region! 

You specify the outline of a region with procedures that draw lines and 
shapes, as described In Section E.9, QuickDraw Routines. An example Is given 
in the discussion of cioseRgn In section E.9.11, calculations with Regions. 

Many calculations can be performed on regions. A region can be "expanded" 
or "shrunk" and, given any two regions, QuickDraw can find their unloa 
intersection, difference, and excluslve-OR; It can also determine whether a 
given point or rectangle Intersects a given region, and so on. There Is of 
course a set of graphic operations on regions to draw them on the screen. 

E.'^ GFapmc EnliUes 

Coordinate planes, points, rectangles, and regions are all good mathematical 
models, but they aren't really graphic elements—they don't have a direct 
physical appearance. Some graphic entitles that do have a direct graphic 
interpretation are the tfJt Jm^e, Dltmafi pattern and cursor. This section 
describes the data structure of these graphic entitles and how they relate to 
the mathematical constructs described above. 

E.4.1 The Bit Image 

A bit Image is a collection of bits In memory which have a rectilinear 
representation. Take a collection of words In memory and lay them end to 
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end so that bit 15 of the lowest-numbered word is on the left and bit of 
the highest-numbered word is on the far right Then take this array of bits 
and divide It, on word boundaries, into a number of equal-size rows, stack 
these rows vertically so that the first row is on the top and the last row is on 
the bottom. The result is a matrix like the one shown in Figure E-5~rows 
and columns of bits, with each row containing the same number of bytes. The 
number of bytes in each row of the bit image is called the row wictw of that 
image. 




Row width 
is 8 bytes 



Figure E-5 
ABU Image 

A bit image can be stored in any static or dynamic variable, and can be of 
any length that is a multiple of the row width. 

The Lisa screen itself is one large visible bit image. There are 32,760 bytes of 
memory that are displayed as a matrix of 262,080 pixels on the screen, each 
bit corresponding to one pixel. If a bit's value is 0, its pixel is white; if the 
bit's value is i, the pixel is black. 

The screen is 364 pixels tall and 720 pixels wide, and the row width of Its bit 
image is 90 bytes. Each pixel on the screen Is one and a half times taller 
than It is wide, meaning a rectangle 30 pixels wide by 20 tall looks square, 
and a 30 by 20 oval looks circular. There are 90 pixels per Inch horizontally, 
and 60 per Inch vertically. 
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NOTE 



Since eacn pixel on tne screen represents one Dlt in a oil Image^ 
wherever this appendix says "blt"^ you can substitute "pixel" if the bit 
image Is the Lisa screen. Likewise^ this appendix often refers to pixels 
on the screen where the discussion applies equally to bits in an 
off-screen bit Image. 



E.4.2 The Bitmap 

When you combine the physical entity of a bit image with the conceptual 
entities of the coordinate plane and rectangle, you get a bitmap. A bitmap 
has three parts: a pointer to a bit Image, the row width (in bytes) of that 
image, and a boundary rectangle which gives the bitmap both Its dimensions 
and a coordinate system. Notice that a bitmap does not actually Include the 
bits themselves: it points to them. 

There can be several bitmaps pointing to the same bit Image, each Imposing a 
different coordinate system on It This Important feature Is explained more 
fully In Section E.6, Coordinates in GrafPorts. 

As shown in Figure E-6, the data structure of a bitmap is as follows: 

type Bittlap - record 

baseAddr: QDPtr; 
roi6ytes: integer; 
txxjnds: Rect 
end; 



Address 



baseAddr 



rowBytes 
bounds 




Figure E-6 
A Bitmap 
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The base/NcMr field is a pointer to tne beginning of the Dlt image in memory^ 
and the rowBytes field Is the number of bytes In each row of the image. Both 
of these should always be even: a bitmap should always begin on a word 
boundary and contain an Integral number of words in each row. 

The bounds field is a boundary rectangle that both encloses the active area of 
the bit image and imposes a coordinate system on It The relationship 
between the boundary rectangle aid the bit image in a bltmsp Is simple yet 
very Important. First, a few general rules: 

• Bits in a bit image fall between points on the coordinate plane. 

• A rectangle divides a bit image into two sets of bits: those bits inside the 
rectangle and those outside the rectangle. 

• A rectangle that is H points wide and v points tall encloses exactly 
(H-l) » (V-1) bits. 

The top left comer of the boundary rectangle is aligned around the first bit in 
the bit image. The width of the rectangle determines how many bits of one 
row are logically owned by the bitmap; the relationship 

8 * inap.ro«6ytes >» map. bounds. right-map. bounds. left 

must always be true. The height of the rectangle determines how many rows 
of the image are logically owned by the bitmap. To ensure that the number 
of bits in the logical bitmap is not larger than the number of bits in the bit 
Image, the bit image must be at least as big as 

(nap . bounds . bottom-map . bounds . top)«map . roveytes 

Normally, the boundary rectangle completely encloses the bit image: the width 
of the boundary rectangle Is equal to the number of bits In one row of the 
Image, and the height of the rectangle Is equal to the number of rows In the 
Image, if the rectangle Is smaller than the dimensions of the Image, the least 
significant bits In each row, as well as the last rows In the Image, are not 
affected by any operatlms on the bitmap. 

The bitmap also Imposes a coordinate system on the Image. Because bits fall 
between coordinate points, the coordinate system assigns Integer values to the 
lines that border and separate bits, not to the bit positions themselves. For 
example, if a bitmap Is assigned the boundary rectangle with comers (10,-8) 
and (34>8), the bottom right bit in the Image will be between horizontal 
coordinates 33 and 34, and between vertical coordinates 7 and 8 (see Figure 
E-7). 
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(ia-8) 



(34,-8) 
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(10,8) 



(34,8) 



Figure E-7 
Coordinates and Bitmaps 



EA3 Patterns 

A pattern Is a 64-bit image^ organized as an 8-dy-8-bit rectangle^ which Is 
used to define a repeating design (such as stripes) or tone (such as gray). 
Patterns can be used to draw lines and shapes or to fill areas on the screen. 

When a pattern is drawn^ it is aligned such that adjacent areas of the same 
pattern in the sanae graphics port will blend with each other into a contin- 
uous, coordinated pattern. QuickDraw provides the predefined patterns wrUte, 
black, gray, ItGray, and dkGray. Any other 64-bit variable or constant can be 
used as a pattern, too. The data type definition for a pattern is as follows: 

type Pattern = packed array [0. .7] of o. .255; 

The row widtn of a pattern Is l byte. 

EA4 CXnrsors 

A cursor is a small Image that appears on the screen and is controlled by the 
mouse. (It appean only on the screen, and never in an off-screen bit Inriage.) 



A cursor Is defined as a 256-dit image, a l6-by-l6-dlt reclar^le. 
width of a cursor is 2 bytes. Figure E-8 illustrates four cursors. 



The row 
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Figure E-8 
CXrrson 

A cursor has three fields: a 16-word data field that contains the Image Itself^ 
a 16-word mask field that contains Information about the screen appearance 
of each bit of the cursor^ and a hotspot point that aligns the cursor with the 
position of the mouse. 

t^pe Cursor = record 

data: array [0..13] of Integer; 
mask: array [0..15] of Integer; 
hotspot: Point 
end; 

The data for the cursor must begin on a word boundary. 

The cursor appears on the screen as a l6-by-l6-blt rectangle. The appear- 
ance of each bit of the rectangle Is determined by the corresponding bits in 
the data and mask and. If the mask bit Is 0^ by the pixel "under" the cursor 
(the one already on the screen In the same position as this bit of the cursor> 



Data 



Mask 






1 


1 


1 








1 






Resulting pixel on screen 

White 

Black 

Same as pixel under cursor 

Inverse of pixel under cursor 

Notice that If all mask bits are 0, the cursor Is completely transparent. In 
that the Image under the cursor can still be viewed: pixels under the white 
part Of the cursor appear unchanged, while under the black part of the cursor, 
black pixels show through as white. 

The hotspot aligns a point In the image (not a bit, a point!) with the mouse 
position. Imagine the rectangle with comers (Oil) and (16,16) framing the 
image, as in each of the examples in Figure E-8; the hotspot is defined In this 
coordinate system. A hotspot of (0,0) is at the top left of the image. For the 
anow in Figure E-8 to point to the mouse position, (0,0) would be its hotspot 
A hotspot of (8^) Is In the exact center of the Image; the center of the plus 
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Figure E-7 
Coordinates and Bitmaps 



E.fl3 Patterns 

A pattern is a 64-blt image, organized as an 8-by-8-Dit rectangle, wnich is 
used to define a repeating design (sucn as stripes) or tone (such as gray). 
Patterns can be used to draw lines and shapes or to fill areas on the screen. 

When a pattern Is drawn. It is aligned such that adjacent areas of the same 
pattern in the same graphics port will blend with each other into a contin- 
uous, coordinated pattern. QuickDraw provides the predefined patterns white, 
black, gray, ItGray, and dkGray. Any other 64-Dit variable or constant can be 
used as a pattern, too. The data type definition for a pattern is as follows: 

type Pattern = packed array [0..7] of 0..255; 

The row width of a pattern Is 1 byte. 

EA4 Cmson 

A cunor is a small image that appean on the screen and is controlled by the 
mouse. (It appears only on the screen, and never in an off-screen bit image.) 

A cursor Is defined as a 256-dit Image, a l6-by-l6-dlt rectargle. The row 
width of a cursor is 2 bytes. Figure E-8 Illustrates four curson. 
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Figure E-8 
Cunon 

A cursor has three fields: a 16-word data field that contains the image itself^ 
a 16-word mask field that contains information about the screen appearance 
of each bit of the cursor, and a hotspot point that aligns the cursor with the 
position of the mouse. 

type Cursor = record 

data: array [0..15] of Integer; 
mask: array [0..1S] of integer; 
hotspot: Point 
end; 

The data for the cursor must begin on a word boundary. 

The cursor appears on the screen as a l6-by-i6-blt rectangle. The appear- 
ance of each bit of the rectangle is determined by the corresponding bits in 
the data and mask and. If the mask bit is 0, by the pixel "under" the cursor 
(the one already on the screen in the same position as this bit of the cursor) 



Data 

1 

1 



Mask 
1 
1 





Resulting pixel on screen 

White 

Black 

Same as pixel under cursor 

Inverse of pixel under cursor 



Notice that If all mask bits are 0, the cursor Is completely transparent, in 
that the image under the cursor can still be viewed: pixels under the white 
part of the cursor appear unchanged, while under the black part of the cursor, 
black pixels show through as white. 

The hotspot aligns a point in the image (not a bit, a point!) with the mouse 
position. Imagine the rectangle with comers (0,0) and (16,16) framing the 
image, as in each of the examples in Figure E-8; the hotspot is defined in this 
coordinate system. A hotspot of (0,0) Is at the top left of the imaga For the 
arrow in Figure E-8 to point to the mouse position, (0,0) would be its hotspot 
A hotspot of (8^) Is in the exact center of the image; the center of the plus 
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sign or oval in Figure E-8 would coincide with the mouse position if (8>8) were 
the hotspot for that cursor. Similarly^ the hotspot for the pointing hand would 
oe (16.9). 

Whenever you move the mouse, the low-level interrupt-driven mouse routines 
move the cursor's hotspot to be aligned with the new mouse position. 

QuickDraw supplies a predefined arrow cursor, an arrow pointing north- 
northwest 

Refer to /Appendix F/ Hardware interface, for more information on the mouse 
and cursor control. 

E.5 The Drawing Environment: GrafPort 

A grafPort is a complete drawing environment that defines how and where 
graphic operations will have their effect. It contains all the information 
ahout one Instance of graphic output that is kept separate from all other 
instances. You can have many grafPorts open at once, and each one will have 
its own coordinate system, drawing pattern, background pattern, pen size and 
location, character font and style, and bitmap in which drawing takes place. 
You can instantly switch from one port to another. GrafPorts are the 
structures on which a program builds windows, which are fundamental to the 
Lisa's "overlapping windows" user interface. 

A grafPort is a dynamic data structure, defined as follows: 



type GrafPtr = ^GrafPort; 




GrafPort = record 




device: 


Integer; 


portBlts: 


Bltriap; 


portRect: 


Rect; 


vlsRgn: 


RgnHandle; 


cllpRgn: 


RgnHandle; 


DkPat: 


Pattern; 


fillPat: 


Pattern; 


pnLoc: 


Point; 


pnSlze: 


Point; 


pnhode: 


Integer; 


pnPat: 


Pattenv 


pnVis: 


integer; 


txFont: 


Integer; 


txFace: 


Style; 


txtlode: 


Integer; 


txSlze: 


Integer; 


spExtra: 


longlnt; 


fgDolor: 


longlnt; 


bkOolor: 


longlnt; 


colrBlt: 


Integer; 


patstretch: 


Integer; 


plcsave: 


QOHandle; 
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rgnsave: QOHandle; 

polySave: QOHandle; 

grafPTocs: OOProcsPtr 
end; 

All QuickDraw operations refer to grafPorts via grafPtrs. You create a 
grafPort with the Pascal procedure new and use the resulting pointer in calls 
to QuickDraw. You could^ of course^ declare a static variaDle of type 
GrafPort^ and obtain a pointer to that static structure (with the • operator), 
txit as most grafPorts will be used dynamically, their data structures should be 
dynamic also, 

NDTC 

You can access all fields and subfields of a grafPort normally, but you 
should not store new values directly into them. QuickDraw has 
procedures for altering all fields of a grafPort, and using these 
procedures ensures that changing a grafPort produces no unusual side 
effects. 



The device field of a grafPort is the number of the logical output device that 
the grafPort will be using. QuickDraw uses this information, since there are 
physical differences in the same logical font for different output devices. The 
default device number is 0, for the Lisa screen. 

The portBits field is the bitmap that points to the bit image to be used by the 
grafPort. All drawing that is done in this grafPort will take place in this bit 
image. The default bitmap uses the entire Lisa screen as its bit image, with 
rowBytes of 90 and a boundary rectangle of (0,0,720,364). The bitmap may be 
changed to indicate a different structure in memory: all graphics procedures 
work in exactly the same way regardless of whether their effects are visible 
on the screea A program can, for example, prepare an image to be printed 
on a printer without ever displaying the image on the screen, or develop a 
picture in an off-screen bitmap before transferring it to the screen. By 
altering the coordinates of the portBitsixiunds rectangle, you can change the 
coordinate system of the grafPort; with a QuickDraw procedure call, you can 
set an arbitrary coordinate system for each grafPort, even if the different 
grafPorts all use the same bit image (e.g., the full screen). 

The portRect field is a rectangle that defines a subset of the bitmap for use 
by the grafPort Its coordinates are in the system defined by the 
portBltsixxjnds rectangle. All drawing done by the application occurs inside 
this rectangle. The portRect usually defines the "writable" interior area of a 
window, document, or other object on the screen. The default portRect is the 
entire screen. 

The visRgn field indicates the region that is actually visible on the screen. It 
is reserved for use Ki)/ future software, and should be treated as read-only. 



E-16 



Pascal Reference Manual 



QuickDraw 



The default vlsRgn Is set to the portRect 

The cllpRgn Is an artiltrary region that the application can use to limit 
drawing to any region within the portRect If^ for example^ you want to draw 
a half circle on the screen, you can set the cllpRgn to half the square that 
would enclose the whole circle, and go ahead and draw the whole circle. Only 
the half within the cllpRgn will actually be drawn in the grafPort The 
default CllpRgn is set art)ltrarlly large, and you have full control over its 
setting. Notice that unlike the vlsRgn, the cllpRgn affects the image even if 
it is not displayed on the screen. 

Figure E-9 Illustrates a typical Dltmap (as defined by portBlls), portRect, 
vlsRgh/ and cllpRgn. 



©jEflj^SQ 










Figure E-9 
GrafPort Regions 

The bkPat and flllPat fields of a grafPort contain patterns used by certain 
QuickDraw routines. BkPat is the "background" pattern that is used when an 
area is erased or when bits are scrolled out of it When asked to fill an area 
with a specified pattern, cjuickDraw stores the given pattern In the flllPat 
field and then calls a low-level drawing routine which gets the pattern from 
that field. The various graphic operations are discussed In detail later in the 
descriptions of individual QuickDraw routines. 

Of the next ten fields, the first five determine characteristics of the graphics 
pen, described in Section E.5.1, and the last five determine characteristics of 
any text that may be drawn, described in Section E.5.2. 

The fgColor, bkColor, and coiiBit fields contain values related to drawing In 
color, a capability that will be available in the future when Apple supports 
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color output devices for the Lisa. FgC5olor is the grafPort's foreground color 
and bkColor is its background color. ColiBit tells the color imaging software 
which plane of the color picture to draw Into. For more Information^ see 
Section E.7.2^ Drawing In Color. 

The patstietch field Is used during output to a printer to expand patterns If 
necessary. The application should not change Its value. 

The picSave^ rgnSave, and polySave fields reflect the state of picture^ region, 
and polygon definition, respectively. To define a regloa for example, you 
"open" It, call routines that draw It, and then "close" it. If no region Is open, 
ignSave contains nil* otherwise, it contains a handle to Information related to 
the region deflnltloa The application should not be concerned about exactly 
what Information the handle leads to; you may, however, save the current 
value of rgnSave, set the field to nil to disable the region definition, and later 
restore It to the saved value to resume the region definition. The picSav/e 
and polySaive fields work similarly for pictures and polygons. 

Finally, the grafProcs field may point to a special data structure that the 
application stores Into If It wants to customize QuickDraw drawing procedures 
or use QuickDraw In other advanced, highly specialized ways. (For more 
Information, see Section E.10, cxistomlzlng QuickDraw Operations.) If 
grafProcs Is rrll, QuickDraw responds in the standard ways described in this 
appendix. 

F 5 1 Pen CtvHTKitfiTistics 

The pnLoc, pnSlze, pnMocie, pnPat and pnVls fields of a grafPort deal with the 
graphics pen. Each grafPort has one and only one graphics pen, which Is used 
for drawing lines, shapes, and text. As lllusuated in Figure E-lO, the pen has 
four Characteristics: a locatioa a size, a drawing mode, and a drawing pattern 
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Figure E-10 
A Grapnics Pen 

The pen location (pnLoc) Is a point In the coordinate system of the grafPort, 
and is where QuickDraw will begin drawing the next line, shape, or character. 
It can be anywhere on the coordinate plane: there are no restrictions on the 
movefnent or placement of the pen. Remember that the pen location is a 
point on the coordinate plane, not a pixel In a bit image! 

The pen is rectangular in shape, and has a user-definable width and height 
(pnsize). The default size is a 1-by-l-bit rectangle; the width and height can 
range from (0,0) to (32767,32767). If either the pen width or the pen height Is 
less than 1, the pen will not draw on the screen. 

• The pen appears as a rectangle with its top left comer at the pen 
location; it hangs below and to the right of the pen location. 

The pnMode and pnPai fields of a grafport determine now the bits under the 
pen are affected when lines or shapes are drawn. The pnPat Is a pattern that 
Is used as the "ink" in the pen. This pattern, like all other patterns drawn in 
the grafPort, is always aligned with the iwrt's coordinate system: the top left 
corner of the pattern is allgied with the top left comer of the portRect, so 
that adjacent areas of the same pattern will blend into a continuous, 
coordinated pattern. Five patterns are predefined (white, black, and three 
shades of gray); you can also create your own pattern and use it as the pnPat 
(A utility procedure, called stuffHex, allows you to fill patterns easily.) 
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The pnMode field determines how the pen pattern Is to affect what's already 
on the bitmap when lines or ^apes are drawn. When the pen draws, 
QuickDraw first determines what bits of the bitmap win be affected and finds 
their corresponding bits In the pattern. It then does a blt-by-blt evaluation 
based on the pen mode, which specifies one of eight boolean operations to 
perform. The resulting bit Is placed Into Its proper place In the bitmap. The 
pen modes are described In section E.7.1, Transfer Modes. 

The, pnS/ls field determines the pen's visibility, that Is, whether It draws on the 
screen. For more Information, see the descriptions of HldePen and ShowPen 
In Section E.9.3, Pen and Llne-Drawlng Routines. 

E.5.2 Text Characteristics 

The txFont, txFace, txMode, txsize, and spExtra fields of a grafPort determine 
how text will be drawn— the font, style, and size of characten and how they 
will be placed on the bitmap. 

QuickDraw can draw characters as quickly and easily as It draws lines and 
shapes, and In many prepared fonts. Figure E-11 shows two QuickDraw 
characters and some terms you should become familiar with. 

ascent line 



ascent 



descent 



\^ 



character 
H width -» 



Q 



base line 



descent line 



Figure E-ll 
GMckOraw Characten 

QuickDraw can display characters In any size, as well as boldfaced. Italicized, 
outlined, or shadowed, all without changing fonts. It can also underline the 
characters, or draw them closer together or farther apart. 

The t)a^oni fleio Is a font number that identifies the character font to be used 
in the grafPort The font number represents the system font, and is the 
default established by cpenPort. The unit QDSupport (listed In section E.15) 
includes definitions of other available font numbers. 

A character font Is defined as a collection of bit images: these Images ma*;e 
up the Individual characters of the font. The characters can be of unequal 
widths, and they're not restricted to their "cells": the lower curl of a 
lowercase j, for example, can stretch back under the previous character 
(typographers call this keming\ A font can consist of up to 256 distinct 
characters, yet not all characters need be defined In a single font. Each font 
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contains a missing symool to be drawn in case of a request to draw a 
character that is missing from the font 

The txFace field controls the appearance of the font with values from the set 
defined by the style data type: 

type styleltem = (dol(t italic^ underline, outline^ snado«, 
condense, extend); 

Style = set of Styleltenu 

You can apply these either alme or in combination (see Figure E-12). Most 
combinations usually look good only for large fonts. 

Normal Characters 
Bold Characters 

M/c C/m'aafers 
Underlined Characters xyi 



Condensed Characters 
Extended Characters 



. . . and in other fonts, too! 

Figure E-12 
Character styles 

If you specify bold, each character is repeatedly drawn one bit to the right an 
appropriate number of times for extra thickness. 

Italic adds an Italic slant to the characters. Character bits above tr« base 
line are skewed right; bits below the base line are skewed left 

underline draws a line below the base line of the characters. If part of a 
Character descends below the base line (as "y" in Figure E-12), the underline is 
not drawn through the pixel on either side of the descending part 

You may specify either outline or shadow. Outline makes a hollow, outlined 
character rather than a solid one. With shadow, not only is the character 
hollow and outlined, but the outline is thickened below and to the right of the 
character to achieve the effect of a shadow. If you specify bold along with 
outline or shadow, the hollow part of the character is widened. 
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Condense and extend affect the horizontal distance between all characters, 
including spaces. Condense decreases the distance between characters and 
extend increases it, by an amount which QuickDraw determines is appropriate. 

The t>Mode field controls the way characters are placed on a bit image. It 
functions much like a pnMode: when a character is drawn, G^ickDraw 
determines which bits of the bit image will be affected, does a bit-by-blt 
comparison based on the mode, and stores the resulting bits into the bit 
image. These modes are described in Section E.7.1, Transfer Modes. Only 
three of them— srcQr, srcXor, and srcBic—should be used for drawing text 

The txsize field specifies the type size for the font, in points (where "point" 
here is a typographical term meaning approximately 1/72 inch). Any size may 
be specified. If QuickDraw does not have the font in a specified size. It will 
scale a size it does have as necessary to produce the size desired. A value of 
In this field directs QuickDraw to choose the size from among those it has 
for the font; it will choose whichever size is closest to the system font size. 

Finally, the spExtra field Is useful when a line of characters is to be drawn 
Justified such that It is aligned with both a left and a right margin (sometimes 
called "full justification"). SpExtra is the number of pixels by which each 
space character should be widened to fill out the line. 

E.6 Coordinates In GrafPorts 

Each grafPort has its own local coordinate system. All fields in the grafPort 
are e>qDressed in these coordinates, and all calculations and actions performed 
In QuickDraw use the local coordinate system of the currently selected port 

Two things are important to remember: 

• Each grafPort maps a portion of the coordinate plane into a similarly- 
sized portion of a bit image. 

• The portBitsixxnds rectangle defines the local coordinates for a grafPort. 

The top left comer of portBits.bounds is always aligned around the first bit in 
the bit image; the coordinates of that corner "anchor" a point on the grid to 
that bit In the bit image. This forms a common reference point for multiple 
grafPorts using the same bit image (such as the screen). Given a 
portBits.txxjnds rectangle for each port, you know that their top left comers 
coincide. 

The interrelationship between the portBitsJX)unds and portRect rectangles is 
very important. As the portBltsixxjnds rectangle establishes a coordinate 
system for the port, the portRect rectangle indicates the section of the 
coordinate plane (and thus the bit image) that will be used for drawing. The 
portRect usually falls inside the portBitsixxjnds rectangle, but it's not required 
to do so. 

When a new grafPort is created. Its bitmap Is set to point to the entire Lisa 
screen^ and both the portBitsinunds and the portRect rectangles are set to 
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720-by-364-Dlt rectangles, vltn the point (0,0) at tne top left corner of the 
screen. 

You can redefine the local coordinates of the top left corner of tne grafPort's 
portRect, using tne SetOrigln procedure. This changes the local coordinate 
system of the grafPort, recalculating the coordinates of all points in the 
grafPort to De relative to the new corner coordinates. For example, consider 
these procedure calls: 

SetPortCgaraePort); 
setorigin(40, 80); 

The call to SetPort sets the current grafPort to gamePort; the call to 
SetOrigln changes the local coordinates of the top left corner of that port's 
portRecl to (40,80) (see Figure E-13). 
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After SetOrigin(4Ci,8Ci) 



Figure E-13 
Changing Local Coordinates 

This recalculates the coordinate conponents of the following elements: 

gamePort'.portBlts.Dounds gamePort". portRect 

ganePort* .vlsRgn 

These elements are always kept "in sync", so that all calculations, compari- 
sons, or operations that seem right, work right. 

Notice that when the local coordinates of a grafPort are offset, the visRgn of 
that port is offset also. Put the clipRgn is not. A good way to think of it is 
that if a document is being shown inside a grafPort, the document "sticks" to 
the coordinate system, ebtkI the port's structure "sticks" to the screen. 
Suppose, for example, that the visRgn and clipRgn in Figure E-13 before 
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Seiorlgln are the same as the portRect, and a document is being shown. After 
the SetOrlgin calL the top left comer of the cllpRgn Is still (95^20), but this 
location has nrwved down and to the right, and the location of the pen within 
the document has similarly moved. The locations of portBitsDounds^ portRect 
and vlsRgn did not change; their coordinates were offset, as always, the top 
left comer of portBitsixxfKis remains aligned around the first bit in the bit 
Image (the first pixel on the screen^ 

If you are moving, comparing, or otherwise dealing with mathematical items in 
different grafPorts (for example, finding the intersection of two regions in two 
different grafPorts), you must adjust to a common coordinate system before 
you perform the operation. A QuickDraw procedure, LocalToGlobal, lets you 
convert a point's local coordinates to a glottal system where the top left 
corner of the bit image is (OJD); by converting the various local coordinates to 
global coordinates, you can compare and mix them with confidence. For more 
Information, see the description of this procedure In Section E.9.17, 
Calculations with Points. 

E.7 General Discussion of Drawing 

Drawing occurs: 

• Always Inside a grafPort, In the bit image and coordinate system defined 
\yi the grafPort's bitmap. 

• Always within the Intersection of the grafPorfs portBlts.bounds and 
portRect, and clipped to its vlsRgn and ollpRgn. 

• Always at the grafPort's pen location. 

• Usually with the grafPorfs pen slze^ pattern, and mode. 

With QuickDraw procedures, you can draw lines, shapes, and text. Shapes 
Include rectangles, ovals, rounded-comer rectangles, wedge-shaped sections of 
ovals, regions, and polygons. 

Lines are defined by two points: the current pen location and a destination 
location. When drawing a line, QuickDraw moves the top left comer of the 
pen along the mathematical trajectory from the current location to the 
destination. The pen hangs below and to the right of the trajectory (see 
Figure E-14). 
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Figure E-14 
Drawing Lines 

NOTC 



t^ mathematical element (such as the pen location) is ever affected by 
clipping; clipping only determines what appears where in the hit image. 
If you draw a line to a location outside your grafPort, the pen location 
will move there^ but only the portion of the line that is inside the port 
will actually be drawn. This is true for all drawing procedures. 



Rectangles, ovals, and rounaed-comer rectangles are defined by two comer 
points. The shapes always appear inside the mathematical rectangle defined 
by the two points. A region is defined in a more complex manner, but also 
appean only within the rectangle enclosing it. Remember, these enclosing 
rectangles have infinitely thin borders and are not visible on the screen. 

As Illustrated In Figure E-15, shapes may be drawn either solid (filled in with 
a pattern) or framed (outlined and hollow). 
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pen 
v/idth 














Figure E-15 
Solid Shapes and Framed Shapes 

In the case of framed shapes, the outline appears completely within the 
enclosing rectangle—with one exception—and the vertical and horizontal 
thickness of the outline is determined by the pen size. The exception is 
polygons, as discussed in section E.8.2, Polygons. 

The pen pattern is used to fill in the bits that are affected by the drawing 
operation. The pen mode defines how those bits are to be affected by 
directing QuickDraw to apply one of eight boolean operations to the bits in 
the shape and the corresponding pixels on the screen. 

Text drawing does not use the pnSlze, pnPai, or pnMooe, but it does use the 
pnLoa Each character is placed to the right of the current pen location, with 
the left end of its base line at the pen's location. The pen Is moved to the 
right to the location where it will draw the next character. No wrap or 
carriage return Is performed automatically. 

The method QuickDraw uses in placing text is controlled by a mode similar to 
the pen mode. This is explained in Section E.7.1, Transfer Modes. Clipping of 
text Is performed in exactly the same manner as all other clipping in 
QuickDraw. 

E.7.1 Transfer Mooes 

When lines or shapes are drawn, the pnMode field of the grafPort determines 
how the drawing is to appear in the port's bit image; similarly, the Dtf^lode 
field determines how text is to appear. There Is also a QuickDraw procedure 
that transfers a bit image from one bitmap to another, and this procedure has 
a mode parameter that determines the appearance of the result. In all these 
cases, the mode, called a transfer mocH specifies one of eight boolean 
operations: for each bit in the item to be drawn, QuickDraw finds the 
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corresponding bit in the destination bit image^ performs the boolean operation 
on tne pair of bits, and stores the resulting bit Into the bit Image. 

There are two types of transfer mode: 

• Pattern transfer mocfes, for drawing lines or shapes with a pattern. 

• Soji/ve transfer modes, for drawing text or transferring aiy bit Image 
between two bitmaps. 

For each type of mode, there are four basic operations—copy. Or, xol and 
Bla The Copy operation simply replaces the pixels In the destination with 
the pixels in the pattern or source, "painting" over the destination without 
regard for what is already tnere. The Qr, Xor, and Blc operations leave the 
destination pixels under the white part of the pattern or source unchanged, 
and differ in how they affect the pixels under the black part: Qr replaces 
those pixels with black pixels, thus "overlaying" the destination with the black 
part Of the pattern or source; Xor Inverts the pixels under the black part; and 
Blc erases them to white. 

Each of the basic operations has a variant in which every pixel In the pattern 
or source Is Inverted before the operation Is performed, giving eight 
operations in all. Each mode Is defined by name as a constant In QuickDraw 
(see Figure E-16)t 






pattern or source 
"Paint" "Overlay' 



destination 
'Invert" "Erase" 






patCopy 
srcCopy 




patOr 
srcOr 



patXor 
srcXor 



patBlc 
srcBIc 





notPatCopy notPatOr 
notSrcCopy notSrcOr 

Figure 
Transfer 



n 

notPatXor notPatBic 
notSrcXor notSrcBic 

E-16 
Modes 
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Pattern source 
transfer transfer 
mode mode 



Action on each pixel In destination: 
If black pixel in If white pixel In 
pattern or source pattern or source 



patcopy 
pator 
patXor 
patBic 

notPatcopy 
notPatOr 
notPatXor 
notPatBic 


srcCopy 
srcor 
srcxor 
srcBic 

notsrccopy 
notSrcQr 
notsrcxor 
notsrcBic 


Force black 
Force black 
Invert 
Force while 

Force white 
Leave alone 
Leave alone 
Leave alone 


Force white 
Leave alone 
Leave alone 
Leave alone 

Force black 
Force black 
Invert 
Force white 



E.7.2 Drawing in Color 

Currently you can only look at QuickDraw output on a black-and-white screen 
or printer. Eventually^ however, Apple will support color output devices. If 
you want to set up your application now to produce color output in the future, 
you can do so by using QuickDraw procedures to set the foreground color and 
the background color. Eight standard colors may be specified with the 
following predefined constants: blackColor, whltecolor, redColor, greenColor, 
blueColor, cyancolor, magentacolor, and yeliowcoior. Initially, the foreground 
color is blackColor and the background color is whiteColor. If you specify a 
color other than whlteColor, It will appear as black on a black-and-white 
output device. 

To apply the table above (in Section E.7.1) to drawing in color, make the 
following translation: where the table shows "Force black"^ read "Force 
foreground color", and where it shows "Force white", read "Force background 
color". When you eventually receive the color output device, you'll find out 
the effect of inverting a color on it. 

NOTE 

QuickDraw can support output devices that have up to 32 bits of color 
information per pixel. A color picture may be thought of, then, as 
having up to 32 planes. At any one time, QuickDraw draws into only 
one of these planes. A QuickDraw routine called by the color-imaging 
software specifies which plane. 

E.8 Pictures and Polygons 

QuickDraw lets you save a sequence of drawing commands and "play them 
back" later with a single procedure call. There are two such mechanisms: one 
for drawing any picture to scale in a destination rectangle that you specify, 
and another for drawing polygons in all the ways you can draw other shapes in 
QuickDraw. 
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E.8.1 Pictures 

A picture in QuickDraw Is a transcript of calls to routines wnich draw 
something— anytning~on a Dltmap, Pictures make It easy for one program to 
draw something defined In another program^ with great flexibility and without 
knowing the details about what's being drawn. 

For each picture you define^ you specify a rectangle that surrounds the 
picture; this rectangle is called the picture fr&ne When you later call the 
procedure that draws the saved picture, you supply a destination rectangle, 
and QuickDraw scales the picture so that Its frame is completely aligned with 
the destination rectangle. Thus, the picture may be expanded or shrunk to fit 
its destination rectangle. For example, if the picture is a circle inside a 
square picture frame, and the destination rectangle Is not square, the picture 
Is drawn as an oval. 

Since a picture may Include any sequence of drawing commands, its data 
structure is a variable-length entity. It consists of two fixed fields followed 
by a variable-length data field: 

type Picture = record 

plcSlze: integer; 
picFrame: Rect; 
{picture definition data} 
end; 

The picSlze field contains the size, in bytes, of the picture variable. The 
picFrame field is the picture frame which surrounds the picture and gives a 
frame of reference for scaling when the picture is drawn. The rest of the 
structure contains a compact representation of the drawing commands that 
define the picture. 

All pictures are accessed through handles, which point to one master pointer 
which In turn points to the picture. 

type PicPtr = ^Picture; 
PlcHandle = TicPtr; 

To define a picture, you call a QuickDraw function that returns a picture 
handle and then call the routines that draw the picture. There is a procedure 
to call when youVe finished defining the picture, and another for when you're 
done with the picture altogether. 

QuickDraw also allows you to intersperse picture comments with the 
definition of a picture. These comments, which do not affect the picture's 
appearance, may be used to provide additional information about the picture 
when it's played back. This Is especially valuable when pictures are 
transmitted from one application to another. There are two standard types of 
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comment wnich^ like parentneses, serve to group drawing commands together 
(such as all the commands that draw a particular part of a picture): 

const plcLParen = 0; 
plcRParen = l; 

The application defining the picture can use these standard comments as well 
as comments of Its own design. 

To Include a comment In the definition of a picture, the application calls a 
QuickDraw procedure that specifies the comment with three parameters: the 
comment kind, which Identifies the type of comment; a handle to additional 
data if desired; and the size of the additional data, if any. When playing back 
a picture, QuickDraw passes any comments In the picture's definition to a 
low-level procedure accessed indirectly through the grafProcs field of the 
grafPort (see Section E.IO, Customizing QuickDraw Operations, for more 
Information^ To process comments, the application must include a procedure 
to do the processing and store a pointer to it in the data structure pointed to 
by the grafProcs field. 

NOTE 

The standard low-level procedure for processing picture connments 
simply Ignores all comments. 

B8.2 Polygons 

Polygons are similar to pictures in that you define them by a sequence of 
calls to QuickDraw routines. They are also similar to other shapes that 
QuickDraw knows about, since there is a set of procedures for performing 
graphic operations and calculations on them. 

A polygm Is simply any sequence of connected lines (see Figure E-17). You 
define a polygon Xy^ moving to the starting point of the polygon and drawing 
lines from there to the next point, from that point to the next, and so on. 




Figure E-17 
Polygons 
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me data structure for a polygon is a varlaDle-lengtn entity, it consists of 
two fixed fields followed by a varlaDle-length array: 

type Polygon = record 

polySlze: integer; 
polyOBox: Rect; 
polyPolnts: array [0..0] of Point 
end; 

The polySlze field contains tne size, in bytes, of the polygon varlaDle. The 
polyBBox field Is a rectangle which just encloses the entire polygon. The 
polyPolnts array expands as necessary to contain the points of the polygon— 
the starting point followed by each successive point to which a line is drawn. 

Like pictures and regions, polygons are accessed through handles. 

type PolyPtr = "Polygon; 
PolyHandle = *PolyPtr; 

To define a polygon, you call a QuickDraw function that returns a polygon 
handle and then form the polygon \y^ calling procedures that draw lines. You 
call a procedure when you've finished defining the polygon, and another when 
you're done with the polygon altogether. 

Just as for other shapes that QuickDraw knows about, there Is a set of 
graphic operations on polygons to draw them on the screen. QuickDraw draws 
a polygon by moving to the starting point and then drawing lines to the 
remaining points In succession, just as when the routines were called to define 
the polygon. In this sense It "plays back" those routine calls. As a result, 
polygons are not treated exactly the same as other QuickDraw shapes. For 
exannple, the procedure that frames a polygon draws outside the actual 
boundary of the polygon, because QuickDraw line-drawing routines draw below 
and to the right of the pen location. The procedures that fill a polygon with 
a pattern, however, stay within the boundary of the polygon; they also add an 
additional line between the ending point and the starting point if those points 
are not the same, to complete the shape. 

There Is also a difference In the way QuickDraw scales a polygon and a 
slmllarly-shgped region If It's being drawn as part of a picture: when 
stretched, a slanted line Is drawn more smoothly If It's part of a polygon 
rather than a region. You may find it helpful to keep In mind the conceptual 
difference between polygons and regions: a polygon Is treated more as a 
continuous shape, a regim more as a set of bits. 

E.9 QuickDraw Routines 

This section describes all the procedures and functions in QuickDraw, their 
parameters, and their operation. They are presented in their Pascal form; for 
information on using them from assembly language, see Section E.11, Using 
QuickDraw from Assembly Language. Note that the actual procedure and 
function declarations are given here, rather than the BNF notation or syntax 
diagrams used elsewhere in this manual. 
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E.9.1 GrafPort Routines 

Procedure inltGraf (globalPtr: (JOPtr); 

InllGraf initializes QuickDraw. It is called by the QOSupport unit's QDlnit 
routine; you need not call it again. It initializes the QuickDraw global 
variables listed below. 

Initial setting 

nil 

all-white pattern 

all-black pattern 

50% gray pattern 

25% gray pattern 

75% gray pattern 

pointing arrow cursor 

Lisa screen, (0A720364) 

1 

The globalPtr parameter tells QuickDraw where to store Its global variables, 
beginning with tnePort From Pascal programs, this parameter should always 
be set to WiePort; assembly-language programmers may choose any location, 
as long as it can accommodate the number of bytes specified by GR/^SIZE In 
GRAFTYPEaTEXT (see Section E.ll, Using QuickDraw from Assembly 
Language). 

NOTE 

To initialize the cursor, call initcursor (described in section E.9.2, 
Cursor-Handling Routines). 



variable 


Type 


thePort 


GrafPtr 


vhite 


Pattern 


black 


Pattern 


gray 


Pattern 


ItGray 


Pattern 


dkGray 


Pattern 


arrow 


Cursor 


screenBits 


Bittiap 


randSeed 


longlnt 



Procedure OpenPort (gp: GrafPtr); 

OpenPort allocates space for the given grafPorfs vlsRgn and cllpRgn. 
Initializes the fields of the grafPort as indicated below, and makes the 
grafPort the current port (see setPort, belowX You must call OpenPort before 
using any grafPort; first create a grafPtr with new, then use that grafPtr in 
the OpenPort call. 
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Field 


Type 


Initial settlna 


device 


Integer 


(Lisa screen) 


portBlts 


Bltriap 


screenBlts (see inliGraf) 


portRect 


Rect 


screenBltsiwunds (0A72O364) 


vlsRgn 


RgnHandle 


nandle to the rectangular region (0A720364) 


cilpRgn 


RgnHandie 


handle to trie rectangular region 
(-3000a -30000. 30000. 30000) 


bkPat 


Pattern 


white 


flllPat 


Pattern 


black 


pnLoc 


Point 


(0^3) 


pnSlze 


Point 


(LI) 


pnhode 


Integer 


patCopy 


pnPat 


Pattern 


DlacK 


prtvis 


integer 


(visible) 


txFont 


Integer 


(system font) 


t>tf^ace 


Style 


normal 


txnode 


Integer 


srcor 


txsize 


integer 


(QuickDraw decides) 


spExtra 


longlnt 





fgColor 


longint 


blackCoior 


bkcoior 


longlnt 


whitecolor 


coirBit 


integer 





patstretch 


Integer 





plcSave 


goHandie 


nil 


rgnsave 


goHandie 


nil 


polySave 


QOHandle 


nil 


grafProcs 


QOProcsPtr 


nil 



Procedure InitPort (gp: GrafPtr); 

Given a pointer to a grafPort that has been opened with openPort. InitPort 
reinitializes the fields of the grafPort and makes it the current port (if it's 
not already)t 

NOTE 

InitPort does everything OpenPort does except allocate space for the 
visRgn and clipRgn. 



Procedure ClosePort (gp: GrafPtr); 

ClosePort deallocates the space occupied by the given grafPorfs vlsRgn and 
ClipRgn. When you are completely through with a grafPort. call this 
procedure. 
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W/MRNINGS 

If you do not call ClosePorl before disposing of the grafPort^ the 
memory used by the visRgn and cllpRgi will be unrecoverable. 

After calling ciosePort^ be sure not to use any copies of the vlsRgn or 
cllpRgn handles that you may have made. 



Procedure SetPort (gp: GrafPtr); 

setPort sets the grafPort indicated by gp to be the current port. The global 
pointer thePort always points to the current port. All QuickDraw drawing 
routines affect the bitmap thePort"4)ortBlt$ and use the local coordinate 
system of thePort*. Note that OpenPort and InitPort do a SetPort to the 
given port. 

WARNING 

Never do a SetPort to a port that has not been opened with OpenPort. 

Each port possesses its own pen and text characteristics which remain 
unchanged when the port is not selected as the current port 

Procedure GetPort (var gp: GrafPtr); 

GetPort returns a pointer to the current grafPort If you have a program that 
draws Into more than one grafPort it's extremely useful to have each 
procedure save the current grafPort (with GetPort), set its own grafPort, do 
drawing or calculations, and then restore the previous grafPort (with SetPort). 
The pointer to the current grafPort is also available through the global 
pointer thePort, but you may prefer to use GetPort for better readability of 
your program text For example, a procedure could do a GetPort(savePon) 
before setting Its own grafPort and a SetPort(savePort) afterwards to restore 
the previous port 

Procedure GrafOevlce (device: Integer); 

GrafDevlce sets thePort". device to the given number, which identifies the 
logical output device for this grafPort cpulckDraw uses this information. The 
initial device number is 0, which represents the Lisa screen. 

Procedure SetPortBits (bin: Bitflap); 

SetPortBits sets thePort "^wrtBits to any previously defined bitmap. This 
allows you to perform all normal drawing and calculations on a buffer other 
than the Lisa screen—for example, a 640-by-8 output buffer for a dot matrix 
printer, or a small off-screen image for later "stamping" onto the screen. 
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Remember to prepare all fields of the bitmap before you call seiPortBlts. 

Procedure PortSize (•idtn,hel^t: integer); 

Portsize changes the size of the current grafPorfs portRecL Tinis does not 
affect the screen; it merely changes the size of the "active area" of the 
grafPort. 

The top left comer of the portRect remains at its same location; the width 
and height of the portRect are set to the given width and height. In other 
words^ Portsize moves the bottom right comer of the portRect to a position 
relative to the top left comer. 

Portsize does not change the cllpRgn or the vlsRgn^ nor does it affect the 
local coordinate system of the grafPort: it changes only the portRect's width 
and height Remember that all drawing occurs only in the intersection of the 
portBitsixxnds and the portRect, clipped to the visRgn and the cllpRga 

Procedure riovePortTo (leftGlobal^topGlobal: integer); 

MovePortTo changes the position of the current grafPort's portRect TTiis does 
not affect tne screen; It merely changes the location at which subsequent 
drawing inside the port will appear. 

The leftGlodal and topGlobal parameters set the distance between the top left 
comer of the portBltsixxjnds and the top left comer of the new portRect 
For example, 

MovePortTo(360, 182),- 

will move the top left comer of the portRect to the center of the screen (if 
portBlts is the Lisa screen) regardless of the local coordinate system. 

Like Portsize, MovePortTo does not change the cllpRgn or the vlsRcn, nor 
does it affect the local coordinate system of the grafPort 

Procedure SetOrigin (h,v: integer); 

SetOrlgin changes the local coordinate system of the current grafPort 77?/^ 
does not affect tfie screen;\i does, however, affect where subsequent drawing 
and calculation will appear In the grafPort SetOrlgin updates the coordinates 
Of the portBltsJt»unds, the portRect, and the visRgn. All subsequent drawing 
and calculation routines will use the new coordinate system. 

The h and V parameters set the coordinates of the top left comer of the 
portRect All other coordinates are calculated from this point All relative 
distances among any elements In the port will remain the same; only their 
absolute local coordinates will change. 
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NQfTE 

setorlgln does not update the coordinates of the cllpRgn or the pen; 
these Items stick to the coordinate system (unlike the port's structure^ 
which sticks to the screen). 

Setorlgln Is useful for adjusting the coordinate system after a scrolling 
operation. (See ScrollRect In Section E.9.13^ Bit Transfer Operations.) 

Procedure Setcilp (rgn: RgnHandle); 

SetCUp changes the clipping region of the current grafPort to a region 
equivalent to the given region. Note that this does not change the region 
handle^ but affects the clipping region Itself. Since SetCllp makes a copy of 
the given region, any suhsequent changes you make to that region will not 
affect the clipping region of the port 

You can set the clipping region to any arbitrary region^ to aid you in drawing 
inside the grafPort The Initial cllpRgn is an arbitrarily large rectangle. 

Procedure Getcilp (rgn: RgnHandle); 

GetCllp changes the given region to a region equivalent to the clipping region 
of the current grafPort. This is the reverse of what setcilp does. Like 
SetClip, it does not change the region handle. 

Procedure cllpRect (r: Rect); 

CllpRect changes the clipping region of the current grafPort to a rectangle 
equivalent to given rectangle. Note that this does not change the region 
handle, but affects the region itself. 

Procedure BackPat (pat: Pattern); 

BackPat sets the background pattern of the current grafPort to the given 
pattern. The background pattern is used in ScrollRect and in all QuickDraw 
routines that perform an "erase" operation. 

E.9.2 Cursor-Handling Routines 

Additional information on cursor handling can be found in Appendix F, 
Hardware Interface. 

Procedure initCursor; 

Inltcursor sets the current cursor to the predefined arrow cursor, an arrow 
pointing north-northwest, and sets the cursor level to 0, making the cursor 
visible. The cursor level, which is Initialized to when the system is booted, 
keeps track of the number of times the cursor has been hidden to compensate 
for nested calls to HideCursor and Showcursor (below). 
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Before you call initCursor, the cursor Is undefined (ol If set Dy a previous 
process^ It's whatever that process set It to). 

Procedure SetOursor (crsr: Cursor); 

SetCursor sets the current cursor to the 16-by-16-0it image In crer. If the 
cursor Is hidden^ It remains hidden and will attain the new appearance when 
It's uncovered; If the cursor Is already visible^ It changes to the new 
appearance Immediately. 

The cursor Image Is Initialized dy initcursor to a north-northwest arrow^ 
visible on the screen. There Is no way to retrieve the current cursor Image. 

Procedure HldeCursor; 

HideCursor removes the cursor from the screen, restoring the bits under It, 
and decrements the cursor level (which Initcursor initialized to 0). Every call 
to HideCursor should be balanced by a subsequent call to ShowCursor. 

Procedure snowCursor; 

ShowCursor increments the cursor level, which may have been decremented by 
HideCursor, and displays the cursor on the screen if the level becomes 0. A 
call to ShowCursor should balance each previous call to HideCursor. The 
level is not incremented beyond 0, so extra calls to ShowCursor don't fxirt. 

if the cursor has been changed (with SetCursor) while hidden, ShowCursor 
presents the new cursor. 

The cursor is initialized by Initcunor to a north-northwest arrow, not hidden. 

Procedure ObscureCursor; 

ObscureCursor hides the cursor until the next time the mouse is moved. Unlike 
HideCursor, it has no effect on the cursor level and must not be balanced by 
a call to ShowCursor. 

E.9.3 Pen and Une-Oraiwlng Routines 

The pen and line-drawing routines all depend on the coordinate system of the 
current grafPort. Remember that each grafPort has its own pen; if you draw 
In one grafPort, change to another, and return to the first, the pen win have 
remained in the same location. 

Procedure HidePen; 

HidePen decrements the current grafPorfs pnVls field, which is initialized to 
by openPort; v/henever pnvis Is negative, the pen does not draw on the 
screen. PnVls keeps track of the number of times the pen has been hidden to 
compensate for nested calls to HidePen and ShowPen (below). HidePen is 
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called by OpenRgn, openPlcUjre, and OpenPoly so that you can define regions, 
pictures, and polygons wltfxjut drawing on the screen. 

Procedure Sho«Pen; 

ShowPen increments the current grafPort's pnVls fields which may have Xse!&[\ 
decremented Dy HldePen; If pnVls becomes 0, QuickDraw resumes drawing on 
the screen. Extra calls to ShowPen will increment pnVis beyond 0, so every 
call to ShowPen should be balanced by a subsequent call to HldePen. 
ShowPen Is called by CloseRgn, ClosePicture, and ClosePoly. 

Procedure GetPen (var pt: Point); 

GetPen returns the current pen location^ in the local coordinates of the 
current grafPort 

Procedure GetPenState (var pnstate: PenState); 

GetPenstate saves the pen location, size, pattern, and mode in a storage 
variable, to be restored later with SetPenState (belowX This is useful when 
calling short subroutines that operate in the current port but must change the 
graphics pen: each such procedure can save the pen's state when it's called^ do 
whatever it needs to do, and restore the previous pen state Immediately 
before returning. 

The PenState data type is not useful for anything except saving the pen's 
state. 

Procedure SetPenState (pnstate: PenState); 

SetPenState sets the pen location, size, pattern, and mode in the current 
grafPort to the values stored in pnState. This is usually called at the end of 
a procedure that has altered the pen parameters and wants to restore them to 
their state at the beginning of the procedure. (See GetPenState, above.) 

Procedure Penslze (width, height: Integer); 

PenSize sets the dimensions of the graphics pen in the current grafPort. All 
subsequent calls to Line, LlneTo, and the procedures that draw framed shapes 
in the current grafPort will use the new pen dimensions. 

The pen dimensions can be accessed in the variable thePort"4)nSlze, which is 
of type Point If either of the pen dimensions is set to a negative value, the 
pen assumes the dimensions (0,0) and no drawing Is performed. For a 
discussion of how the pen draws, see Section E.7, General Discussion of 
Drawing. 
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Rrocedure Pennode (mode: Integer); 

PenMode sets the transfer mode througn which the pnPat is transferred onto 
the bitmap when lines or shapes are drawn. The mode may be any one of the 
pattern transfer modes: 

patoopy patxoT notPatOopy notPatxor 

pator patBlc notPator notPatBlc 

If the mode is one of the source transfer modes (or negative), no drawing is 
performed. The current pen mode can be obtained in the variable 
thePort''4)nMod& The initial pen mode is patCopy, in which the pen pattern 
is copied directly to the bitmap. 

Procedure PenPat (pat: Pattern); 

PenPat sets the pattern that is used by the pen in the current grafPort. The 
standard patterns white, black, gray, ItGray, and dkGray are predefined; the 
initial pen pattern Is black. The cunent pen pattern can be obtained in the 
variable thePort"4)nPat, and this value can be assigned (but not compared!) to 
any other variable of type Pattern. 

Procedure PenNorinal; 

PenNormal resets the initial state of the pen in the current grafPort, as 
follows: 

Field Setting 

pnSlze (1,1) 

pnhode patOopy 

pnPat black 

The pen location is not changed. 

Procedure Movelo (h,v: integer); 

MoveTo moves the pen to location (>vv) in the local coordinates of the current 
grafPort. No drawing is performed. 

Procedure Move (dh,dv: Integer); 

Move moves the pen a distance of dh horizontally and dv vertically from its 
current location; It calls MoveTo(h+dh,v+dv), where (!h,v) Is the current location. 
The positive directions are to the right and down. No drawing Is performed. 
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Procedure LlneTo (r\,v: integer); 

LineTo draws a line from the current pen location to tne location specified (in 
local coordinates) by h and v. The new pen location Is (h,v) after the line Is 
drawn. See Section E.7, General Discussion of Drawing. 

If a region or polygon Is open and being formed. Its outline Is Infinitely thin 
and Is not affected by the pnsize, pnMode, or pnPat (See openRgn and 
OpenPoly.) 

Procedure Line (dh^dv: Integer); 

Line draws a line to the location that Is a distance of dh horizontally and dv 
vertically from the current pen location; it calls LlneTo(h-Kfvv+dv), where (h,v) 
Is the current location. The positive directions are to the right and down. 
The pen location becomes the coordinates of the end of the line after the line 
is drawn. See Section E.7, General Discussion of Drawing. 

If a region or polygon Is open and being formed. Its outline Is infinitely thin 
and is not affected by the pnSlze, pnMode, or pnPat (See OpenRgn and 
OpenPoly.) 

E.9.4 TextHDrawlng Routines 

Each grafPort has its own text characteristics, and all these procedures deal 
with those of the current port. 

Procedure TextFont (font: integer); 

TextFont sets the current grafPort 's font (thePort".t)tf^ont) to the given font 
number. The initial font number is 0, which represents the system font. For 
other font numbers, refer to the QOSupport unit, listed in Section E.15. 

Procedure TextFace (face: Style); 

TextFace sets the current grafPorfs character style (tnePorl'.txFace). The 
style data type allows you to specify a set of one or more of the following 
predefined constants: bold, italic, underline, outline, snadow, condense, and 
extend. For example: 

TextFace( [bold] ); (bold) 

TextFace( [bold, Italic]); {bold and Italic) 

TextFace(tnePort*.txFace+[bold]); {whatever it was plus bold} 

TextFace(tnePort*.txFaDe-[bold]); {whatever It was but not bold) 

TextFace( [ ] ); {noniBl} 
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Procedure Textnode (mode: integer); 

TextMode sets the current grafPort's transfer mode for drawing text 
(thePort".txMode). The mode should be srcOr^ srcXor, or srcBlc. The initial 
transfer mode for drawing text is srcOr. 

Procedure Textsize (size: Integer); 

TextSize sets the current grafPort's type size (thePort'.txSlze) to the given 
number of points. Any size may be specified, but the result will look best if 
QuickDraw has the font in that size (otherwise it will scale a size it does 
have). The next best result will occur if the given size is an even multiple of 
a size available for the font. If is specified, QuickDraw will choose one of 
the available sizes—whichever is closest to the system font size. The initial 
txSize setting is a 

Procedure spaceExtra (extra: Integer); 

SpaceExtra sets the cunent grafPort's spExtra field, which specifies the 
number of pixels by which to widen each space in a line of text This is 
useful when text is being fully Justified (that is, aligned with both a left and a 
right margin). Consider, for example, a line that contains three spaces; if 
there would normally be six pixels between the end of the line and the right 
margin, you would call SpaceExlra(2) to print the line with full justification. 
The initial spExtra setting is 0. 

NOTE 

SpaceExtra will also t^e a negative argument, but be careful not to 
narrow spaces so much that the text is unreadable. 



Procedure DraiChar (ch: char); 

DrawChar places the given character to the right of the pen location, with 
the left end of its base line at the pen's location, and advances the pen 
accordingly, if the character is not in the font, the font's missing symbol is 
drawn. 

Procedure Drawstring (s: Str255); 

Drawstring performs consecutive calls to DrawChar for each character In the 
supplied string; the string is placed beginning at the current pen location and 
extending right No formatting (carriage returns, line feeds, etc.) is performed 
by QuickDraw. The pen location ends up to the right of the last character in 
the string. 



E-41 



Pascal Reference Manual QuickDraw 

Procedure oravText (texta^f : QOPtr; flrstByte^byteCount: Integer); 

DrawText draws text from an arbitrary structure In memory specified by 
textBuf, starting flrslByte bytes Into the structure and continuing for 
byteCount bytes. The string of text Is placed beginning at the current pen 
location and extending right. No formatting (carriage returns, line feeds, etc.) 
Is performed by QuickDraw. The pen location ends up to the right of the last 
character In the string. 

Function CharVldth (ch: char) : integer; 

ChaiWidth returns the value that will be added to the pen horizontal 
coordinate If the specified character Is drawn. CharWldth Includes the effects 
of tne stylistic variations set with TextFace; if you change these after 
determining the character width but before actually drawing the character, 
the predetermined width may not be correct. If the character is a space, 
CharWldth also Includes the effect of SpaceExtra 

Function StrlngWdtn (s: Str255) : integer; 

StrlngWldth returns the width of the given text string, which It calculates by 
adding the widths of all the characters in the string (see CharWldth, above). 
This value will be added to the pen horizontal coordinate if the specified 
string is drawn. 

Function TextlPidth (textBuf: QOPtr; firstByte, byteCount: integer) : 
Integer; 

TextWldth returns the width of the text stored In the arbitrary structure in 
memory specified by textBuf, starting flrstByte bytes into the structure and 
continuing for byteCount bytes. It calculates the width by adding the widths 
of all the characters in the text. (See CharWldth, above.) 

ProcoJure GetFontlnfo (var info: Fontlnfo); 

GetFontlnfo returns the following Information about the current grafPort's 
character font, taking into consideration the style and size in which the 
characters will be drawn: the ascent, descent, maximum character width (the 
greatest distance the pen will move when a character is drawn), and leading 
(the vertical distance between the descent line and the ascent line below it), 
all In pixels. The Fontinfo data structure is defined as: 

type Fontlnfo = record 

ascent: integer; 
descent: integer; 
vidhax: Integer; 
leading: integer 
end; 
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E.95 Drawing In color 

These routines will enable applications to do color drawing in the future when 
Apple supports color output devices for the Lisa. All nonwhlte colors will 
appear as black on black-and-white output devices. 

Procedure ForeColor (color: longlnt); 

ForeColor sets the foreground color for all drawing in the current grafPort 
(thePort\fgC»lor) to the given color. The following standard colors are 
predefined: blackColor, whiteColor^ redColoL greenColor^ blueColor, cyanColor, 
magentaColoL and yellowColor. The initial foreground color Is blackColor. 

Procedure BackColor (color: longlnt); 

BackColor sets the background color for all drawing In the current grafPort 
(thePorl'iJkColor) to the given color. Eight standard colors are predefined 
(see ForeColor, above). The Initial background color Is whltecolor. 

Procedure ColorBit (nhicfiBit: integer); 

ColorBlt is called by printing software for a color printer, or other color- 
Imaging software, to set the current grafPort's colrBlt field to wnichBit; this 
tells QuickDraw which plane of the color picture to draw into. QuickDraw 
will draw into the plane corresponding to bit number wnichBlt since 
QuickDraw can support output devices that have up to 32 bits of color 
Information per pixel, the possible range of values for whichBIt is through 
51. The Initial value of the colrBlt field is o. 

E.9^ Calculations with Rectangles 

Calculation routines are Independent of the cunent coordinate system; a 
calculation will operate the same regardless of which grafPort is active. 

NOTE 

Remember that if the parameters to one of the calculation routines 
were defined in different grafPorts, you must first adjust them to be in 
the same coordinate system. If you do not adjust them, the result 
returned by the routine may be different from what you see on the 
screen. To adjust to a common coordinate system, see LocalToQlobal 
and GiobaiToLocal in section E.9.17, Calculations with Points. 

Procedure SetRect (var r: Rect; left^ top, rights txjttom: integer); 

SetRect assigns the four boundary coordinates to the rectangle. The result is 
a rectangle with coordinates (left,topjrl^ti)ottom). 

This procedure is supplied as a utility to help you shorten your program text. 
If you want a more readable text at the expense of length, you can assign 
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Integers (or points) directly into the rectangle's fields. There Is no significant 
code size or execution speed advantage to either method; one's just easier to 
write, and the other's easier to read. 

Procedure OffsetRect (var r: Rect; dTvdv: integer); 

OffsetRect moves the rectangle Xi'j adding dh to each horizontal coordinate 
and dv to each vertical coordinate. If dh and dv are positive, the movement 
is to the right and down; if either Is negative, the corresponding movement is 
in the opposite direction. The rectangle retains its shape and size; it's merely 
moved on the coordinate plane. This does not affect the screen unless you 
subsequently call a routine to draw within the rectangle. 

Procedure insetRect (var r: Rect; dh,dv: integer); 

InsetRect shrinks or expands the rectangle. The left and right sides are 
moved in by the amount specified by dh; the top and bottom are moved 
toward the center by the amount specified by dv. If dh or dv is negative, the 
appropriate pair of sides is moved outward instead of Inward. The effect Is to 
alter the size by 2*dh horizontally and 2*dv vertically, with the rectangle 
remaining centered in the same place on the coordinate plane. 

If the resulting width or height becomes less than 1, the rectangle is set to 
the empty rectangle (0,0,0,0). 

Function SectRect (srcRectA^srcRectB: Rect; var dstRect: Rect) : 
Dooieaa- 

SectRect calculates the rectangle that is the intersection of the two input 
rectangles, and returns true if they indeed Intersect or false if they do not. 
Rectangles that "touch" at a line or a point are not considered intersecting, 
because their intersection rectangle (really, in this case, an intersection line 
or point) does not enclose any bits on the bitmap. 

If the rectangles do not intersect, the destination rectangle is set to (0,0,0,0). 
SectRect works correctly even if one of the source rectangles is also the 
destination. 

Procedure UhionRect (srcRectA,srcRectB: Rect; var dstRect: Rect); 

UnionRect calculates the smallest rectangle which encloses both input 
rectangles. It works correctly even If one of the source rectangles Is also the 
destination. 
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Function PtinRect (pt: Point; r: Rect) : IDoolean; 

PtInRect determines whether the pixel Delow and to the right of the given 
coordinate point Is enclosed In the specified rectangle^ and returns true If so 
or false If not. 

Procedure Pt2Rect (ptA^ptB: Point; var dstRect: Rect); 

Pt2Rect returns the smallest rectangle which encloses the two input points. 

Procedure PtToAngle (r: Rect; pt: Point; var angle: Integer); 

PtToAngle calculates an Integer angle between a line from the center of the 
rectangle to the given point and a line from the center of the rectangle 
pointing straight up (12 o'clock high). The angle is in degrees from to 359, 
measured clockwise from 12 o'clock^ with 90° at 3 o'clock, 180" at 6 o'clock, 
and 270" at 9 o'clock. Other angles are measured relative to the rectangle: If 
the line to the given point goes through the top right corner of the rectangle, 
the angle returned is as degrees, even if the rectangle is not square; if it goes 
through the bottom right corner, the angle is 135 degrees, and so on (see 
Figure E-18). 



angle = 45 



angle = 45 




Figure E-18 
PtToAngle 

The angle returned might be used as input to one of the procedures that 
manipulate arcs and wedges, as described In section E.9.10, Graphic operations 
on Arcs and Wedges. 

Function EqualRect (rectA^rectB: Rect) : boolean; 

EqualRect compares the two rectangles and returns true if they are equal or 
false if not. The two rectangles must have identical boundary coordinates to 
be considered equal. 
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Function EmptyRect (r: Rect) : txnlean; 

EmptyRect returns tiue if the given rectangle 1$ an empty rectangle or false 
if not A rectangle is considered empty if the bottom coordinate is equal to 
or less than the top or the right coordinate is equal to or less than the left. 

E.9.7 Graphic Gpeiations on Rectangles 

These procedures perform graphic operations on rectangles. See also 
ScrollRect in Section E.9.13^ Bit Transfer Operations. 

Procedure FraneRect (r: Rect); 

FrameRect draws an outline just Inside the specified rectangle, using the 
current grafPort's pen pattern, mode, and size. The outline Is as wide as the 
pen width and as tall as the pen height. It is drawn with the pnPat, according 
to the pattern transfer mode specified by pnMode. The pen location is not 
changed by this procedure. 

If a region is open and being formed, the outside outline of the new rectangle 
is mathematically added to the region's boundary. 

Procedure PalntRect (r: Rect); 

PaintRect paints the specified rectangle with the current grafPort's pen 
pattern and mode. The rectangle on the bitmap is filled with the pnPat, 
according to the pattern transfer mode specified by pnMode. The pen location 
is not changed by this procedure. 

Procedure EraseRect (r: Rect); 

EraseRect paints the specified rectangle with the current grafPort's back- 
ground pattern bkPat (in patCopy mode). The grafPort's pnPat and pnMode are 
ignored; the pen location is not changed. 

Procedure InvertRect (r: Rect); 

InvertRect inverts the pixels enclosed by the specified rectaigle: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat, pnMode, and bkPat are all Ignored; the pen location is not changed. 

Procedure FillRect (r: Rect; pat: Pattern); 

FillRect fills the specified rectangle with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is 
not changed. 
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E.9.8 Graphic Gperatlons on CA/als 

ovals are drawn Inside rectangles that you specify. If the rectangle you 
specify Is square, QuickDraw draws a circle. 

Procedure FranieOval (r: Rect); 

FrameOval draws an outline just Inside the oval that fits Inside the specified 
rectangle, using the current grafPort's pen pattern, mode, and size. The 
outline Is as wide as the pen width and as tall as the pen height. It Is drawn 
with the pnPat, according to the pattern transfer mode specified by pnMode. 
The pen location Is not changed by this procedure. 

If a region Is open and being formed, the outside outline of the new oval Is 
mathematically added to the region's boundary. 

Procedure PaintOval (r: Rect); 

PalntOval paints an oval just inside the specified rectangle with the current 
grafPort's pen pattern and mode. The oval on the bitmap is filled with the 
pnPal, according to the pattern transfer mode specified by pnMode. The pen 
location is not changed by this procedure. 

Procedure EraseOval (r: Rect); 

EraseOval paints an oval just inside the specified rectangle with the current 
grafPort's background pattern bkPat (in patCopy modeX The grafPort's pnPat 
and pnMode are ignored; the pen location is not changed. 

Procedure InvertOval (r: Rect); 

InvertOval inverts the pixels enclosed by an oval just inside the specified 
rectangle: every white pixel becomes black and every black pixel becomes 
white. The grafPort's pnPat, pnMode, and bkPal are all ignored; the pen 
location is not changed. 

Procedure FillOval (r: Rect; pat: Pattern); 

FlUOval fills an oval just inside the specified rectangle with the given pattern 
(in patCopy mode). The grafPort's prPat, pnMode, and bkPat are all ignored; 
the pen location is not changed. 

E.9.9 Graphic operations on RoundechComer Rectangles 

Procedure FraineRoundRect (r: Rect; ovalWidth^ovalHelg^t: integer); 

FrameRoundRect draws an outline just inside the specified rounded-corner 
rectangle, using the current grafPort's pen pattern, mode, and size. Ch/alWidth 
and ovalHelght specify the diameters of curvature for the comers (see Figure 
E-19X The outline is as wide as the pen width and as tall as the pen height. 
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It is drawn with the pnPat according to the pattern transfer nrjode specified 
by pnMode. The pen location is not changed by this procedure. 
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Figure E-19 
Rounded-Comer Rectangle 

If a region is open and being formed, the outside outline of the new rounded- 
corner rectangle is mathematically added to the region's boundary. 

Procedure PalntRoundRect (r: Rect; ovaiWdtn^ovaiHel^t: integer); 

PalntRoundRect paints the specified rounded-corner rectangle with the 
current grafPort's pen pattern and mode. O/alWidth and ovalHeight specify 
the diameters of curvature for the corners. The rounded-corner rectangle on 
the bitmap is filled with the pnPat, according to the pattern transfer mode 
specified by pnMode. The pen location is not changed by this procedure. 

Procedure EraseRoundRect (r: Rect; ovalWidth, ovalHelc^t: integer); 

EraseRoundRect paints the specified rounded-comer rectangle with the 
current grafPort's background pattern bkPat (in patCopy mode). OvalWidth and 
ovalHeight specify the diameters of curvature for the corners. The grafPort's 
pnPat and pnMode are ignored; the pen location is not changed. 

Procedure InvertRoundRect (r: Rect; ovalWidth, ovalHeight: integer); 

invertRoundRect Inverts the pixels enclosed by the specified rounded-corner 
rectangle: every white pixel becomes black and every black pixel becomes 
white. O/aiWidth and ovalHel^t specify the diameters of curvature for the 
comers. The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 
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Procedure FlllRoundRect 



(r: Rect; oval»idth,ovalHel^t: Integer; pat: 
Pattern); 



FlllRoundRect fills the specified rounded-corner rectangle with ine given 
pattern (In patCopy mode). CValwldtn and ovalHelght specify the diameters of 
curvature for the comers. The grafPorfs pnPat, pnMode, and dkPat are all 
ignored; the pen location Is not changed. 

E.9.10 Graphic Operations on Arcs and Wedges 

These procedures perform graphic operations on arcs and wedge-shaped 
sections of ovals. See also PtToAngle in Section E.9.6^ Calculations with 
Rectangles. 

Procedure FrameArc (r: Rect; startAngle^arcAngle: Integer); 

FrameArc draws an arc of the oval that fits Inside the specified rectangle, 
using the current grafPort's pen pattern, mode, and size. StartAngle Indicates 
where the arc Begins and is treated mod 360, ArcAngle defines the extent of 
the arc. The angles are given in positive or negative degrees; a positive angle 
goes clockwise, while a negative angle goes counterclockwise, zero degrees is 
at 12 o'clock high, 90" (or -270*) is at 3 o'clock, 180" (or -180**) is at 6 
o'clock, and 270" (or -90") is at 9 o'clock. Other angles are measured relative 
to the enclosing rectangle: a line from the center of the rectangle through Its 
top right corner is at 45 degrees, even if the rectangle is not square; a line 
through the bottom right comer is at 135 degrees, and so on (see Figure E-20). 



StartAngle = 

|arcAngle = 45 



StartAngle =0 StartAngle = 



arcAngle=-45j 




StartAngle = 

arcAngle = 45 



FrameArc 




PaintArc 



Figure E-20 
Operations on Arcs and Wedges 
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The arc Is as wide as the pen wldtn and as tall as the pen height. It Is drawn 
with the pnPat according to the pattern transfer mode specified py pnMode. 
The pen location is not changed by this procedure. 

WARNING 

FrameArc differs from other QuickDraw procedures that frame shapes 
in that the arc is not mathematically added to the boundary of a 
region that is open and being formed. 



Procedure PaintArc (r: Rect; startAngle^aroAngle: Integer); 

PalntArc paints a wedge of the oval just inside the specified rectangle with 
the current grafPort's pen pattern and mode. StartAngle and arcAngle define 
the arc of the wedge as in FrameArc. The wedge on the bitmap is filled with 
the pnPat according to the pattern transfer mode specified by pnMode. The 
pen location is not changed by this procedure. 

Procedure EraseArc (r: Rect; startAngle^arcAngle: integer); 

EraseArc paints a wedge of the oval Just inside the specified rectangle with 
the current grafPort's background pattern bkPat (In patCopy mode). 
StartAngle and arcAngle define the arc of the wedge as in FrameArc. The 
grafPort's pnPat and pnMode are Ignored; the pen location is not changed. 

Procedure InvertArc (r: Rect; startAngle^ arcAngle: integer); 

invertArc Inverts the pixels enclosed by a wedge of the oval just Inside the 
specified rectangle: every white pixel becomes black and every black pixel 
becomes white. StartAngle and aroAngle define the arc of the wedge as In 
FrameArc. The grafPort's pni^u pnMode^ and dkPat are all Ignored; the pen 
location is not changed. 

Procedure FillArc (r: Rect; StartAngle^ arcAngle: integer; pat: 
Pattern); 

FillArc fills a wedge of the oval just inside the specified rectangle with the 
given pattern (in patCopy mode) StartAngle and arcAngle define the arc of 
the wedge as in FrameArc. The grafPort's pnPat pnMode^ and dkPat are all 
Ignored; the pen location Is not changed. 
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E.9.11 calculations wltn Regions 

NOTE 

RennemDer that if the parameters to one of the calculation routines 
were defined in different giafPorts. you must first adjust them to De In 
the same coordinate system. If you do not adjust them^ the result 
returned Dy the routine may De different from what you see on the 
screen. To adjust to a common coordinate system^ see LocalToGlobal 
and GlohalToLocai In Section E.9.17. Calculations with Points. 



Function NewRgn : RgnHandle; 

NewRgn allocates space for a new, dynamic, varlaoie-slze region. Initializes it 
to the empty region (0,0A0), and returns a handle to the new region. Only 
this function creates new regions; all other procedures just alter the size and 
shape of regions you create. OpenPort calls NewRgn to allocate space for the 
port's vlsRgn and clipRgn. 

W/>RN1NGS 

Except when using vlsRgn or clipRgn, you must call NewRgn before 
specifying a region's handle In any drawing or calculation procedure. 

Ntever refer to a region without using Its handle. 



Procedure DisposeRgn (rgn: RgnHandle); 

DisposeRgn deallocates space for the region whose handle Is supplied, and 
returns the memory used Ki^ the region to the free memory pool, use this 
only after you are completely through with a temporary region. 

WARNING 

Never use a region once you have deallocated It, or you will risk being 
hung by dangling pointers! 



Prcx^edure CopyRgn (srcRgn,dstRgn: RgnHandle); 

CopyRgn copies the mathematical structure of srcRgn into dstRgn; that Is, it 
makes a duplicate copy of srcRgn. once this Is done, srcRgn may be altered 
(or even disposed of) without affecting dstRgn. CopyRgn does not create the 
destination region you must use NewRgn to create the dstRgn before you 
call CopyRgn. 
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Procedure SetEinptyRgn (rgn: RgnHandle); 

SetEmpiyRgn destroys the previous structure of the given region, then sets the 
new structure to the empty region (0,OJ],0)l 

Procedure SetRectRgn (rgn: RgnHandle; left^ top, ri^t, bottom: integer); 

SetRectRgn destroys the previous structure of the given region, then sets the 
new structure to the rectangle specified by left, top, right, and bottom. 

If the specified rectangle is empty (l.e., left>-rl^t or top>-bottom), the region 
is set to the empty region (0,0^3,0). 

Procedure RectRgn (rgn: RgnHandle; r: Rect); 

RectRgn destroys the previous structure of the given region, then sets the new 
structure to the rectangle specified by r. This is operationally synonymous 
with SetRectRgn, except the input rectangle is defined tnj a rectangle rather 
than by four boundary coordinates. 

Procedure OpenRgn; 

OpenRgn tells QuickDraw to allocate temporary space and start saving lines 
and framed shapes for later processing as a region definition. While a region 
is open, all calls to Line, LineTo, and the procedures that draw framed shapes 
(except arcs) affect the outline of the region. Only the line endpolnts and 
shape boundaries affect the region definition; the pen mode, pattern, and size 
do not affect It. In fact, OpenRgn calls HldePen, so no drawing occurs on the 
screen while the region is open (unless you called ShowPen just after OpenRgn, 
or you called ShowPen previously without balancing it Xi)i a call to HldePen). 
Since the pen hangs below and to the right of the pen location, drawing lines 
with even the smallest pen will change bits that lie outside the region you 
define. 

The outline of a region is mathematically defined and infinitely thin, and 
separates the bitmap into two groups of bits: those within the region and 
those outside it. A region should consist of one or more closed loops. Each 
framed shape itself constitutes a loop. Any lines drawn with Line or LineTo 
should connect with each other or with a framed shc^e. Even though the 
on-screen presentation of a region Is clipped, the definition of a region Is not; 
you can define a region anywhere on the coordinate plane with complete 
disregard for the location of various grafPort entitles on that plane. 

When a region is open, the current grafPort's rgnSave field contains a handle 
to Information related to the region definition. If you want to temporarily 
disable the collection of lines and shapes, you can save the current value of 
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tnis fields set the field to nit and later restore the saved value to resume the 
region definition. 

WARNING 

Do not call OpenRgn while another region is already open. All open 
regions Out the most recent will behave strangely. 



Procedure CloseRgn (dstRgn: RgnHandle); 

CloseRgn stops the collection of lines and framed shapes, organizes them into 
a region definition, and saves the resulting region Into the region Indicated Dy 
dstRgn. You should perform one and only one CloseRgn for every OpenRgn. 
CloseRgn calls ShowPen, balancing the HidePen call made by OpenRgn. 

Here's an example of how to create and open a region, define a barbell shape, 
close the region, and draw It: 

barbell := NewRgn; {make a new region} 

OpenRgn; {begin collecting stuff) 

setRect(tenpRect,20,20,30,50); {form the left weic^t} 

FraineOval(tefnpRect); 

setRect(tenpRect,30,30,80,40); {form the bar) 

FraineRect(tempRect); 

setRect(teirpRect,80,20,9a50); {form the ri^t weight) 

FraineOval(teinpR8Ct); 

closeRgn(barbell); {we're done; save in barbell) 

FillRgn(barbell^ black); {draw it on the screen) 

DlsposeRgn(barbell); {we don't need you anymora..) 

Procedure OffsetRgn (rgn: RgnHandle; dh^dv: Integer); 

QffsetRgn moves the region on the coordinate plane, a distance of dh 
horizontally and dv vertically. This does not affect the screen unless you 
subsequently call a routine to draw the region. If dh and dv are positive, the 
movement Is to the right and down; If either Is negative, the corresponding 
movement Is In the opposite direction. The region retains its size and shape. 

NOTE 

OffsetRgn Is an especially efficient operation, because most of the data 
defining a region Is stored relative to rgnBBox and so Isn't actually 
changed Xi\i OffsetRgn. 
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Procedure insetRgn (rgn: RgnHandle; dh^dv: Integer); 

inselRgn shrinks or expands the region. All points on the region boundary are 
moved inwards a distance of dv vertically and dh horizontally; if dh or dv is 
negative, the points are moved outwards in that direction. InsetRgn leaves 
the region "centered" at the same position, but moves the outline in (for 
positive values of dh and dv) or out (for negative values of dh and dv). 
InsetRgn of a rectangular region works just like InsetRect. 

Procedure SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

SectRgn calculates the intersection of two regions and places the intersection 
in a third region. This does not create t/je destJnatJon region: you must use 
NewRgn to create dslRgn before you call SectRgn. The dslRgn can be one of 
the source regions, if desired. 

If the regions do not intersect, or one of the regions Is empty, the destination 
is set to the empty region (0,0,0,0). 

Procedure unlonRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

UnionRgn calculates the union of two regions and places the union in a third 
region. TNs does not create tne destination region: you must use NewRgn to 
create dstRgn before you call UnionRgn. The dstRgn can be one of the 
source regions, if desired. 

If both regions are empty, the destination Is set to the empty region (0,OAOX 

Procedure DiffRgn (srcRgnA^srcRgnB, dstRgn: RgnHandle); 

DlffRgn subtracts srcRgnB from srcRgnA and places the difference in a third 
region. This ODes not create tne destination region- you must use NewRgn to 
create dstRgn before you call DiffRgn. The dstRgn can be one of the source 
regions. If desired. 

If the first source region Is empty, the destination is set to the empty region 
(0,0,0,0). 

Procedure XorRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle); 

xorRgn calculates the difference between the union and the intersection of 
two regions and places the result In a third region. T/tls dc^s mt create tt^ 
destination region: you must use NewRgn to create dstRgn before you call 
XorRgn. The dstRgn can be one of the source regions, if desired. 

If the regions are coincident, the destination is set to the empty region 
(0,0,0,0). 
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Function PtInRgn (pt: Point; rgn: RgnHandle) : boolean; 

PtInRgn checks whether the pixel delow and to the right of the given 
coordinate point Is within the specified region^ and returns true If so or false 
If not. 

Function RectlnRgn (r: Rect; rgn: RgnHandle) : txx)lean; 

RectlnRgn checks whether the given rectangle Intersects the specified region, 
and returns true If the Intersection encloses at least one hit or false if not. 

Function EqualRgn (rgn/\,rgnB: rgnHandle) : boolean; 

EqualRgn compares the two regions and returns true If they are equal or false 
If not. The two regions must have Identical sizes, shapes, and locations to be 
considered equal. Any two empty regions are always equal. 

Function EnptyRgn (rgn: RgnHandle) : boolean; 

EmptyRgn returns true If the region Is an empty region or false If not. Some 
of the circumstances In which an empty region can be created are: a NewRgn 
call; a CopyRgn of an empty region; a SetRectRgn or RectRgn with an empty 
rectangle as an argument; CloseRgn without a previous OpenRgn or with no 
drawing after an OpenRgn; OffsetRgn of an empty region; InsetRgn with an 
empty region or too large an Inset; SectRgn of nonlntersectlng regions; 
UnionRgn of two empty regions; and DiffRgn or XorRgn of two Identical or 
nonlntersectlng regions. 

B9.12 Graphic Operations on Regions 

These routines all depend on the coordinate system of the cunent grafPort. If 
a region Is drawn In a different grafPort than the one In which It was defined. 
It may not appear in the proper position Inside the port 

Procedure FraraeRgn (rgn: RgnHandle); 

FrameRgn draws a hollow outline Just Inside the specified region, using the 
current grafPorfs pen pattern, mode, and size. The outline is as wide as the 
pen width and as tall as the pen height; under no circumstances will the 
frame go outside the region boundary. The pen location is not changed by 
this procedure. 

If a region Is open and being formed, the outside outline of the region being 
framed Is mathematically added to that region's boundary. 

Procedure PaintRgn (rgn: RgnHandle); 

PaintRgn paints the specified region with the current grafPort's pen pattern 
and pen mode. The region on the bitmap Is filled with the pnPat, according 
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to the pattern transfer mode specified Dy pnMode. The pen location is not 
changed by this procedure. 

Procedure EraseRgn (rgp: RgnHandle); 

EraseRgn paints the specified region with the current grafPort's background 
pattern DkPal (in patcopy mode). The grafPort's pnPat and pnMode are 
ignored; the pen location is not changed. 

Procedure invertRgn (rgn: RgnHandle); 

InvertRgn inverts the pixels enclosed by the specified region: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat, pnMode^ and bkPal are all ignored; the pen location is not changed. 

Procedure FlllRgn (rgn: RgnHandle; pat: Pattern); 

FillRgn fills the specified region with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode^ and bkPat are all ignored; the pen location is 
not changed. 

E.9.13 Bit Transfer Operations 

Procedure ScrollRect (r: Rect; dh^dv: Integer; updateRgn: RgnHandle); 

ScroURect shifts C'scroiis") those bits inside the intersection of the specified 
rectangle^ visRgn^ clipRgn, portRect and portBltsJaounds. The bits are shifted 
a distance of dh horizontally and dv vertically. The positive directions are to 
the right and down. No other bits are affected. Bits that are shifted out of 
the scroll area are lost; they are neither placed outside the area nor saved. 
The grafPort's background pattern bkPat fills the space created by the scroll. 
In addition updateRgn is changed to the area filled with bkPat (see Figure 
E-21). 
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Figure E-21 
scrolling 

Figure E-21 snows that tne pen location after a ScroliRect Is In a different 
position relative to wnat was scrolled in tne rectangle. Tne entire scrolled 
Item nas Deen moved to different coordinates. To restore it to Its coordinates 
before tne ScroliRect, you can use tne SetOrigin procedure. For example, 
suppose tne dsiReci nere Is tne portRect of tne grafport and its top left 
corner is at (95,120). Sel0rigln(1054l5) will offset tne coordinate system to 
compensate for tne scroll. Since tne cUpRgn and pen location are not offset, 
tney move down and to the left 

Procedure CopyBits (srcBlts^dstBlts: BltMap; srcRect^dstRect: Rect; 
mode: Integer; masKRgn: RgnHandle); 

copyBits transfers a Pit Image between any two bitmaps and clips tne result 
to the area specified by the masKRgn parameter. Tne transfer may be 
performed in any of tne eight source transfer modes. The result is always 
clipped to the maskRgn and the boundary rectangle of the destination bitmap; 
if tne destination bitmap is tne current grafPorfs portBlts, it is also clipped 
to the intersection of the grafPorfs ollpRgn and visRgn. If you do not want 
to clip to a masKRgn, just pass nil for the maskRgn parameter. 

The dstRect and maskRgn coordinates are in terms of the dstBltsiwunds 
coordinate system, and the srcReci coordinates are in terms of the 
STcBitsixxjnds coordinates. 

The bits enclosed by the source rectangle are transferred into the destination 
rectangle according to tne rules of the chosen mode. 
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The source transfer modes are as follows: 



srcCopy 
srcQr 



srcxor 
srcBlc 



notSrcCopy 
notSrcQr 



notSrcXor 
notSrcBic 



The source rectangle Is completely aligned with the destination rectangle; if 
the rectangles are of different sizes, the bit image is expanded or shrunk as 
necessary to fit the destination rectangle. For example, if the hit image is a 
circle in a square source rectangle, and the destination rectangle is not 
square, the bit image appears as an oval in the destination (see Figure E-22). 
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Figure E-Z2 
operation of CopyBits 



E.9.14 Picturej 



Function openPlcture (plcFrame: Rect) : PlcHandie; 

OpenPicture returns a handle to a new picture which has the given rectangle 
as its picture frame, and tells QuickDraw to start saving as the picture 
definition all calls to drawing routines and all picture comments (If any). 

OpenPlcture calls HldePen, so no drawing occurs on the screen while the 
picture is open (unless you call ShowPen just after OpenPicture, or you called 
ShowPen previously without balancing It by a call to HldePen). 

When a picture Is open, the current grafPort's picSave field contains a handle 
to Information related to the picture definition. If you want to temporarily 
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dlsaDie the collection of routine calls and picture comments, you can save tne 
current value of this field, set the field to nil, and later restore the saved 
value to resume tne picture definition. 

WARNING 

Do not call openPlcture while another picture is already open. 



Procedure ClosePlcture; 

ClosePicture tells QuickDraw to stop saving routine calls and picture 
comments as the definition of the currently open picture. You should perform 
one and only one ClosePlcture for every OpenPlcture. ClosePlcture calls 
ShowPen, balancing the HldePen call made by OpenPlcture. 

Procedure PicCoraroent (kind^dataSize: integer; dataHandle: QOHandle); 

Plccomment Inserts the specified comment into the definition of the currently 
open picture. Kind identifies the type of comment. DataHandle Is a handle 
to additional data if desired, and dataSize is the size of that data in Dytes. If 
there Is no additional data for the comment, dataHandle should be nil and 
dataSize should be o. The application that processes the comment must 
Include a procedure to do the processing and store a pointer to the procedure 
m the data structure pointed to by the grafProcs field of the grafPort (see 
Section E.10, Customizing QuickDraw Operations). 

Procedure DravPlcture (myPicture: PlcHandle; dstRect: Rect); 

DrawPlcture draws the given picture to scale In dstRect, expanding or 
shrinking It as necessary to align the borders of the picture frame with 
dstRect DrawPlcture passes any picture comments to the procedure accessed 
Indirectly through the grafProcs field of the grafPort (see Plccomment above). 

Procedure KillPicture (uiyPicture: PicHandle); 

KiiiPicture deallocates space for the picture whose handle is supplied, and 
returns the memory used by the picture to the free memory pool. Use this 
only when you are completely through with a picture. 

E.9.15 Calculations with Polygons 

Function OpenPoly : PolyHandle; 

CpenPoly returns a handle to a new polygon and tells QuickDraw to start 
saving the polygon definition as specified by calls to line-drawing routines. 
While a polygon is open, all calls to Line and LineTo affect the outline of the 
polygon. Only the line endpoints affect the polygon definition; the pen mode, 
pattern, and size do not affect it. In fact, OpenPoly calls HldePen, so no 
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drawing occurs on the screen while tne polygon Is open (unless you call 
ShowPen Just after openPoly^ or you called ShowPen previously without 
Balancing It Dy a call to HldePen). 

A polygon should consist of a sequence of connected lines. Even though the 
on-screen presentation of a polygon is clipped^ the definition of a polygon Is 
not; you can define a polygon anywhere on the coordinate plane with complete 
disregard for the location of various grafPort entities on that plane. 

When a polygon is open, the current grafPort's polySave field contains a 
handle to information related to the polygon definition. If you want to 
temporarily dlsaDle the polygon definition, you can save the current value of 
this field, set the field to nil, and later restore the saved value to resume the 
polygon definition. 

WARNING 

Do not call OpenPoly while another polygon Is already open. 



Procedure closePoly; 

ClosePoly tells QuickDraw to stop saving the definition of the currently open 
polygon and computes the polyBBox rectangle. You should perform one and 
only one ClosePoly for every OpenPoly. ClosePoly calls ShowPen, balancing 
the HldePen call made xx^ OpenPoly. 

Here's an example of how to open a polygon, define it as a triangle, close It, 
and draw It: 

save handle and begin collecting stuff} 
" move to first point and 
forro 
the 
triangle 
stop collecting stuff 
cirav It on the screen 
we're all done 



trlPoly := OpenPoly; 

MoveTo(300, 100); 

LlneTo(400,200); 

LineTo(200.200); 

LlneTo(30a 100); 
ClosePoly; 

FlllPoly(trlPoly, gray); 
KillPoly(triPoly); 



Procedure KlllPoly (poly: PolyHandle); 

KillPoly deallocates space for the polygon whose handle is supplied, and 
returns the memory used ti)i the polygon to the free memory pool, use this 
only after you are completely through with a polygon. 

Procedure OffsetPoly (poly: PolyHandle; dh^dv: integer); 

OffsetPoly moves the specified polygon on the coordinate plane, a distance of 
dh horizontally and dv vertically. This does not affect the screen unless you 
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suDsequentiy call a routine to araw the polygon. If dn and dv are positive, 
the movement is to the right and down; if either is negative, the correspond- 
ing movement is In the opposite direction. The polygon retains its shape and 
size. 

NOTE 

OffsetPoly is an especially efficient operation, because the data 
defining a polygon is stored relative to polystart and so isn't actually 
changed by OffsetPoly. 

E.9.16 Graphic Operations on Polygons 

Procedure FramePoly (poly: PolyHandle); 

FramePoly plays back the line-drawing routine calls that define the given 
polygon, using the current grafPort's pen pattern, mode, and size. The pen 
will hang below and to the right of each point on the boundary of the 
polygon; thus, the polygon drawn will extend beyond the right and bottom 
edges of poly" '*4»lyBBox by the pen width and pen height, respectively. All 
other graphic operations occur strictly within the boundary of the polygon, as 
for other shapes. You can see this difference in Figure E-23, where each of 
the polygons is shown with its polyBBox 





FramePoly 



pQJntPoly 



Figure E-23 
Diav^hg Polygons 



if a polygon is open and being formed, FramePoly affects the outline of the 
polygon just as if the line-drawing routines themselves had been called. If a 
region is open and being formed, the outside outline of the polygon being 
framed is mathematically added to the region's boundary. 
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Procedure PalntPoly (poly: PolyHandle); 

PalntPoly paints the specified polygon with the current grafPort's pen pattern 
and pen mode. The polygon on the bitmap is filled with the pnPat according 
to the pattern transfer mode specified by pnModa The pen location is not 
changed by this procedure. 

Procedure ErasePoly (poly: PolyHandle); 

ErasePoly paints the specified polygon with the current grafPort's background 
pattern bkPat (in patCopy mode). The pnPat and pnMode are ignored; the pen 
location is not changed. 

Procedure InvertPoly (poly: PolyHandle); 

invertPoly inverts the pixels enclosed by the specified polygon: every white 
pixel becomes black and every black pixel becomes white. The grafPort's 
pnPat^ pnMode^ and bkPat are all ignored; the pen location is not changed. 

Procedure FillPoly (poly: PolyHandle; pat: Pattern); 

FiiiPoly fills the specified polygon with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is 
not changed. 

E.9.17 calculauons With Points 

Procedure AddPt (srcPt: Point; var dstPt: Point); 

AddPt adds the coordinates of srcPt to the coordinates of dstPt, and returns 
the result in dstPt 

Procedure SubPt (srcPt: Point; var dstPt: Point); 

SubPt subtracts the coordinates of srcPt from the coordinates of dstPt, and 
returns the result in dstPt 

Procedure SetPt (var pt: Point; h,v: integer); 

SetPt assigns two integer coordinates to a variable of type Point 

Function EqualPt (ptA^ptB: Point) : boolean; 

EqualPt compares the two points and returns true if they are equal or false if 
not 
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Procedure LocalToGlobal (var pt: Point); 

LocalToGlobal converts the given point from tne current grafPort's local 
coordinate system Into a global coordinate system wltn tne origin (0^) at tne 
top left comer of tne port's bit Image (sucn as tne screen), mis global point 
can tnen be compared to otner global points^ or be cnanged into tne local 
coordinates of anotner grafPort 

Since a rectangle is defined by two points^ you can convert a rectangle Into 
global coordinates by performing two LocalToGlobal calls. You can also 
convert a rectangle, region, or polygon into global coordinates by calling 
OffsetRect, OffsetRgn. or OffsetPoly. For examples, see GlobalToLocal below. 

Procedure GlodalToLocal (var pt: Point); 

GlobalToLocal takes a point expressed in global coordinates (with tne top left 
corner of tne bitmap as coordinate (0,0)) and converts it into tne local 
coordinates of the current grafPort. The global point can be obtained wltn 
tne LocalToGlobal call (see above). For example, suppose a game draws a 
"ball" within a rectangle named t)aIlRect, defined in the grafPort named 
gamePort (as illustrated below in Figure E-24). If you want to draw that ball 
in the grafPort named selectPort, you can calculate the ball's seiectPort 
coordinates like this: 

SetPort(garoePort); { start In origin port } 

selectBall := ballRect; { make a copy to be moved } 

LocalToGlot)al(select6all.topLeft); { put Doth comers Into } 

LocalToGlot)al(selectBall.botRlght); { global coordinates } 

SetPort(selectPort); { switch to destination port) 

61obalToLocal(select8all.topLeft); { put both corners Into ) 
GlobalToLocal(selectBall.botRlght);{ these local coordinates } 
F1110val(selectBall,DallColor); { no« you have the ball! ) 
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Figure E-Z4 
Converting between Coordinate Systems 

You can see from Figure E-24 that LocalToGlobal and GlobalToLocal simply 
offset the coordinates of the rectangle by the coordinates of the top left 
corner of the local grafPort's boundary rectangle. You could also do this with 
OffsetRect. In fact^ the way to convert regions and polygons from one 
coordinate system to another Is. with OffsetRgn or OffsetPoly rather than 
LocalToGlobal ana GlobalToLocal. For example. If myRgn were a region 
enclosed by a rectangle having the same coordinates as ballRect in gamePort 
you could convert the region to global coordinates with 

OffsetRgn(myRgn, -20^ -40); 
and then convert it to the coordinates of the selectPort grafPort with 

OffsetRgn(myRgn, 15, -30); 
E.9.18 Miscellaneous UUliUes 
Function Random : integers- 
Random returns an integer, uniformly distributed pseudo-random, in the range 
from -32768 through 32767. The value returned depends on the global 
variable randSeed, which initGraf initializes to 1; you can start the sequence 
over again from where it began by resetting randSeed to i. 
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Function GetPlxel (r\,v: integer) : boolean; 

GetPlxel looks at the pixel associated with the given coordinate point and 
returns true if It Is Dlack or false If It is white. The selected pixel is 
immediately below and to the right of the point whose coordinates are given 
in h and v, in the local coordinates of the current grafPort. There is no 
guarantee that the specified pixel actually belongs to the port, however; it 
may have been drawn by a port overlapping the current one. To see if the 
point indeed belongs to the current port, call PtInRgn(pt,tnePort".visRgn> 

Procedure stuff Hex (tningPtr: goPtr; s: str255); 

StuffHex pokes bits (expressed as a string of hexadecimal digits) into any data 
structure. This is a good way to create cursors, patterns, or bit images to be 
"stamped" onto the screen with CopyBits. For example. 

Stuff Hex(astrlpes^ ' 0102040810204080') 

places a striped pattern into the pattern variable stripes. 
WARNING 

There is no range checking on the size of the destination variable. It's 
easy to overrun the variable and destroy something if you don't know 
what you're doing. 



Procedure scalePt (var pt: Point; srcRect,dstRect: Rect); 

A width and height are passed in pt; the horizontal component of pt is the 
width, and the vertical component of pt is the height. ScalePt scales these 
measurements as follows and returns the result in pt it multiplies the given 
width by the ratio of dslRect's width to srcRect's width, and multiplies the 
given height Xi)i the ratio of dslRect's height to srcRect's height, in Figure 
E-25, where dstRect's width is twice srcRect's width and Its height Is three 
times srcRect's height, the pen width Is scaled from 3 to 6 and the pen height 
Is scaled from 2 to 6. 
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ScalePt scales pen size (3,2) to (6,6) 
MapPt maps point (3,2) to (18,7) 

Figure E-25 
ScalePt and MapPt 

Procedure MapPt (var pt: Point; srcRect^dstRect: Rect); 

Given a point within sicRect MapPt maps it to a similarly located point 
within dstRect (that is, to where it would fall if it were part of a drawing 
being expanded or shrunk to fit dstRect). The result is returned in pt A 
corner point of sicRect would be mapped to the corresponding comer point of 
dstRect and the center of srcRect to the center of dstRect In Figure E-25 
above, the point (3,2) In srcRect is mapped to (18,7) In dstRect FromRect and 
dstRect may overlap, and pt need not actually be within sn^ect 
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WARNIIMG 

Remember^ if you are going to draw Inside the rectangle In dstRect 
you will probably also want to scale the pen size accordingly with 
ScalePt. 

Procedure ttapRect (var r: Rect; srcRect^ dstRect : Rect); 

Given a rectangle witnin srcRect, MapRect maps it to a similarly located 
rectangle witnin dstRect by calling MapPt to map the top left and bottom 
right corners of the rectangle. The result is returned in r. 

Procedure ttapRgn (rgn: RgnHandle; srcRect^dstRect: Rect); 

Given a region within srcRect, MapRgn maps it to a similarly located region 
within dstRect by calling MapPt to map all the points in the region. 

Procedure MapPoly (poly: PolyHandle; srcRect^ dstRect: Rect); 

Given a polygon within srcRect, MapPoly maps It to a similarly located 
polygon within dstRect by calling MapPt to map all the points that define the 
polygon. 

E.10 Customizing QuickDraw Operations 

For each shape that QuickDraw knows how to draw^ there are procedures that 
perform these basic graphic operations on the shape: frame, paint, erase, 
invert, and fill. Those procedures in turn call a low-level drawing routine for 
the shape. For example, the FrameOval, PalntOval, EraseOval, InvertOval, and 
Filioval procedures all call a low-level routine that draws the oval. For each 
type of object QuickDraw can draw, including text and lines, there is a 
pointer to such a routine. By changing these pointers, you can install your 
own routines, and either completely override the standard ones or call them 
after your routines have modified parameters as necessary. 

Other low-level routines that you can Install in this way are: 

• The procedure that does bit transfer and is called by CopyBits. 

• The function that measures the width of text and is called by CharWidth, 
Strlngwidth, and Textwidth. 

• The procedure that processes picture comments and is called \y^ 
DrawPicture. The standard such procedure ignores picture comments. 

• The procedure that saves drawing commands as the definition of a picture, 
and the one that retrieves them. This enables the application to draw on 
remote devices, print to the disk, get picture input from the disk, and 
support large pictures. 
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The grafProcs field of a grafPort determines which low-ievei routines are 
called; if It contains nil, the standard routines are called^ so that all 
operations In that grafPort are done In the standard ways described In this 
appendix. You can set the grafProcs field to point to a record of pointers to 
routines. The data type of grafProcs is QDProcsPtr: 



type QDProcsPtr = *QDProcs, 






QOPruus = record 






textProc: 


QDPtr; 


text drawing} 


lineProu: 


QOPtr; 


line drawing} 


rectProc: 


QDPtr; 


rectangle drawing} 


rRectProc: 


QOPtr; 


{roundRect drawing} 


ovalProc: 


QDPtr; 


oval drawing} 


arcProc: 


QOPtr; 


arc/wedge drawing} 


polyProc: 


QOPtr; 


{polygon drawing} 


rgnProc: 


QOPtr; 


region drawing} 


bltsProc: 


QOPtr; 


{bit transfer} 


coimientProc: 


QOPtr; 


picture coninent 
processing} 


txMeasProc: 


QOPtr; 


{text width raeastireiiEnt} 


getPicProc: 


QOPtr; 


{pict4jre retrieval} 


putPlcProc: 


QOPtr 


{picture saving} 



end; 



Procedure SetStdProcs (var procs: QOProcs); 

SetStdProcs is provided to assist you In setting up a QDProcs record. It sets 
all the fields of the given QDProcs to point to the standard low-level 
routines. You can then change the ones you wish to point to your own 
routines. For example^ if your procedure that processes picture comments is 
named MyComments^ you will store fiMyComments in the commentProc field 
of the QDProcs record. 

The routines you Install must of course have the same calling sequences as 
the standard routines^ which are described below. The standard drawing 
routines tell which graphic operation to perform from a parameter of type 
GrafVert). 

type GrafVerb = (frame, paint, erase, invert, fill); 

When the grafVerb Is fllL the pattern to use when filling Is passed In the 
flUPat field of the grafPort. 

Procedure stdlext (byteCount: integer; textBuf: QOPtr; numer,denoiii: 
Point); 

StdText Is the standard low-level routine for drawing text. It draws text from 
the arbitrary structure in memory specified by textBuf, starting from the first 
byte and continuing for byteCount bytes. Numer and denom specify the 
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scaling. If any: numer.v over denomv gives the vertical scaling, and numer.h 
over denomii gives the horizontal scaling. 

Procedure StdLine (newPt: Point); 

StdLine is the standard low-level routine for drawing a line. It draws a line 
from the current pen location to the location specified (in local coordinates) 
Py newPt 

Procedure StdRect (verb: Graf Vert); r: Rect); 

StdRect is the standard low-level routine for drawing a rectangle. It draws 
the given rectangle according to the specified grafvert). 

Procedure StdRRect (verb: Graf Verb; r: Rect; oval«»idtn,ovalHelght: 
integer); 

StdRRect is the standard low-level routine for drawing a rounded-corner 
rectangle. It draws the given rounded-corner rectangle according to the 
specified grafVertx O^width and ovalHelght specify the diameters of 
curvature for the comers. 

Procedure StdOval (verb: Graf Verb; r: Rect); 

stdOval is the standard low-level routine for drawing an oval, it draws an 
oval inside the given rectangle according to the specified grafVerb. 

Procedure StdArc (verb: GrafVerb; r: Rect; startAngle^arcAngle: 
integer); 

StdArc Is the standard low-level routine for drawing an arc or a wedge, it 
draws an arc or wedge of the oval that fits inside the given rectangle. The 
grafveib specifies the graphic operation; if it's the frame operation^ an arc is 
drawn; otherwise^ a wedge is drawn. 

Procedure StdPoly (verb: GrafVerb; poly: PolyHandle); 

StdPoly is the standard low-level routine for drawing a polygon. It draws the 
given polygon according to the specified grafVerb. 

Procedure StdRgn (verb: GrafVerb; rgn: RgnHandle); 

StdRgn is the standard low-level routine for drawing a region. It draws the 
given region according to the specified grafVerb. 
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Procaedure StdBlts (var srcBlts: Bltflap; var srcRect,dstRect: Rect; 
mode: Integer; maskRgn: RgnHandle); 

StdBlts is the standard low-level routine for doing bit transfer. It transfers a 
bit Image between the given bitmap and thePort 4»rtBits^ just as if CopyBits 
were called with the same parameters and with a destination bitmap equal to 
thePort"^rtBlts. 

Procedure StdConinent (klnd^datasize: integer; dataHandle: QDHandle); 

StdComment is the standard low-level routine for processing a picture 
comment. Kind identifies the type of comment. DataHandle is a handle to 
additional data, and dataSize is the size of that data in bytes. If there Is no 
additional data for the command^ dataHandle will be nil and dataSlze will be 
0. StdComment simply ignores the comment. 

Function StdTxMeas (byteCount: Integer; textBuf : QOPtr; var nuiner, 
denoin: Point; var info: Fontlnfo) : integer; 

StdTxMeas is the standard low-level routine for measuring text width. It 
returns the width of the text stored in the arbitrary structure in memory 
specified by textBuf, starting with the first byte and continuing for byteCount 
bytes. Numer and denom specify the scaling as in the StdText procedure; note 
that StdTxMeas may change them. 

Procedure StdGetPic (dataPtr: QOPtr; byteCount: integer); 

StdGetPic is the standard low-level routine for retrieving information from 
the definition of a picture. It retrieves the next byteCount bytes from the 
definition of the currently open picture and stores them in the data structure 
pointed to by dataPtr. 

Proc^Sure StdPutPic ((fetaPtr: ijDPtr; byteCount: Integer); 

stdPutPlc is the standard low-level routine for saving information as the 
definition of a picture. It saves as the definition of the currently open 
picture the drawing commands stored in the data structure pointed to ti^ 
dataPtr, starting with the first byte and continuing for the next byteCount 
bytes. 
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E.11 Using QuickDraw from Assembly Language 

All QuickDraw routines can be called from assembly-language programs as 
well as from Pascal. When you write an assembly-language program to use 
these routines^ though^ you must emulate Pascal's parameter passing and 
variable transfer protocols. 

This section discusses now to use the QuickDraw constants^ global variables, 
data types, procedures, and functions from assembly language. 

The primary aid to assembly language programmers is a file named 
QD/GRAFTYPES.TEXT. If you use .INCLUDE to Include this file when you 
assemble your program, all the QuickDraw constants, offsets to locations of 
global variables, and offsets Into the fields of structured types will be 
available in symbolic form. 

E.11.1 Constanu 

QuickDraw constants are stored in the QD/GRAFTYPES.TEXT file, and you 
can use the constant values symbolically. For example. If you've loaded the 
effective address of the thePort ".ixMode field Into address register A2, you 
can set that field to the sicXor mode with this statement: 

MOVE.i iSRCX0R,(A2) 

To refer to the number of bytes occupied by the QuickDraw global variables, 
you can use the constant GRAFSIZE. v/hen you call the InltGraf procedure, 
you must pass a pointer to an area at least that large. 

E.ll^ Data Types 

Pascal's strong typing ability lets you write Pascal programs without really 
considering the size of a variable. But in assembly language, you must keep 
track of the size of every variable. The sizes of the standard Pascal data 
types are as follows: 



Type 


Size 


integer 


word (2 bytes) 


longint 


Long (/I bytes) 


txx)lean 


Word (2 bytes) 


char 


Word (2 bytes) 


leal 


Long (4 bytes) 



Integers and longints are in two's complement form; booieans have their 
boolean value in bit 8 of the word (the low-order bit of the byte at the same 
location); Chan are stored in the high-order byte of the word; and reals are in 
the KCS standard format 
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The QuickDraw simple data types listed below are constructed out of these 
fundamental types. 



Type 


Size 


guptr 


Long (4 bytes) 


QDHandle 


Long (4 bytes) 


word 


Long (a bytes) 


Slr255 


Page (256 bytes) 


Pattern 


8 bytes 


Bitsl6 


32 bytes 



Other data types are constructed as records of variables of the above types. 
The size of such a type is the sum of the sizes of all the fields in the record; 
the fields appear In the variable with the first field In the lowest address. 
For example, consider the data type BitMap, which is defined as follows: 

type Bitttap = record 

baseAddr: QOPtr; 
rowBytes: integer; 
bounds: Rect 
end; 

This data type would be arranged In memory as seven words: a long for the 
baseAddr, a word for the rowBytes, and four words for the top, left, right, and 
bottom parts of the bounds rectangle. To assist you In referring to the fields 
inside a variable that has a structure like this, the GIDA3RAFTYPES.TEXT file 
defines constants that you can use as offsets Into the fields of a structured 
variable. For example, to move a bitmap's rowBytes value into D3, you would 
execute the following Instruction: 

ttOVE.i «YBITMAP+R0I»BYTES,03 

Displacements are given in the QDA3RAFTYPES.TEXT file for all fields of all 
data types defined by QuickDraw. 

To do double Indirection, you perform an LEA indirectly to obtain the 
effective address from the handle. For example, to get at the top coordinate 
of a region's enclosing rectangle: 

MOVE.L riYHANDLE,Al ; Load handle into Al 

mvE.L (Ai),Al ; Use handle to get pointer 

MOVE.i RGNB80X*TOP(Al),D3 ; Load value using pointer 
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For regions (and all other varlaDle-length structures with handles^ you 
must not move tne pointer Into a register once and just continue to use 
tnat pointer; you must do tne double Indirection each time. Every 
QuickDraw call you make can possibly trigger a heap compaction that 
renders all pointers to movable neap Items (like regions) Invalid. The 
handles will remain valld^ but pointers you've obtained through handles 
can be rendered Invalid at any subroutine call or trap In your program. 

E.11.3 Global Variables 

Register A5 always points to the section of memory where global variables 
are stored. The G3D/GRAFTYPES.TEXT file defines a constant GRAFGLCB 
that points to the beginning of the QuickDraw variables In this space, and 
other constants that point to the Individual variables. To access one of the 
variables, put GRAFGLOB in an address register, sum the constants, and index 
off of that register. For example. If you want to know the horizontal 
coordinate of the pen location for the current grafPort, which the global 
variable IhePort points to, you can give the following Instructions: 

noVE.L GRAFGL0B(A5),A0 ; Point to QuickDraw globals 
MOVE.L THEPORT(AO),Al ; Get current grafPort 

noVE.W PNLOC*H(A1).DO ; Get thePort\pnLoc.h 

E.11-4 Procedures and Functions 

To call a QuickDraw procedure or function, you must push all parameters to It 
on the stack, then JSR to the function or procedure. When you link your 
program with QuickDraw, these JSRs are adjusted to refer to QuickDraw's 
jump table, so that a JSR Into the table redirects you to the actual location 
of the procedure or function. 

The only difficult part about calling QuickDraw procedures and functions Is 
stacking the parameters. You must follow some strict rules: 

• Save all registers you wish to preserve before you begin pushing 
parameters. Any QuickDraw procedure or function can destroy the 
contents of the registers AO, Al, DO, Dl, and D2, but the others are never 
altered. 

• Push the parameters In the order that they appear In the Pascal procedural 
Interface. 

• For booleans, push a byte; for Integers and characters, push a word; for 
pointers, handles, long Integers, and reals, push a long. 

• For any structured variable longer than 4 bytes, push a pointer to the 
variable. 
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• For all var parameters, regardless of size, push a pointer to tne variable. 

• When calling a function, fii^t push a null entry equal to the size of the 
function result, t/ien push all other parameters. The result will be left on 
the stack after the function returns to you. 

This makes for a lengthy interface, but it also guarantees that you can mock 
up a Pascal venion of your program, and later translate it into assembly code 
that works the same. For example, the Pascal statement 

blackness := GetPlxel(50,iiiousePos.v); 

would be written in assembly language like this: 

; Save space for boolean result 

; Push constant 50 (decimal) 

; Push the value of mousePos.v 

; Call routine 

; Fetch result from stack 

This is a simple example, pushing and pulling word-long constants. Normally, 
you'll be pushing more pointers, using the PEA (Push Effective Address) 
Instruction: 

FlllRoundRect(niyRect, \, thePort* . pnsize . v^ white); 

PEA MYRECT ; Push pointer to BiyRect 

MOVE.i #l^-(SP) ; Push constant i 

MOVE.L GRAFGL0B(A5),A0 ; Point to QuickDraw globals 

MOVE.L THEPORT(AO),Al ; Get current grafPort 

MOVE.W PNSIZE*V(A1), -(SP) ; Push value of thePort". pnsize. v 

PEA IPHITE(AO) ; Push pointer to global variable iihite 

JSR FILLROUNDRECT ; Call the subroutine 

To call the TextFace procedure, push a word in which each of seven bits 
represents a stylistic variation: set bit for bold, bit 1 for italic, bit 2 for 
underline, bit 3 for outline, bit 4 for shadow, bit 5 for condense, and bit 6 for 
extendi 



ap.i 


-(SP) 


novE.i 


#50, -(SP) 


MOVE.i 


MdlSFPOS+V, -(SP) 


JSR 


GETPIXEL 


MOVE.* 


(SP)+, BLACKNESS 
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E.1Z Graf3D: TDree-Dlmenslonal Graphics 

Graf3D helps you map tnree-dlmensional Images onto the two-dimensional 
space used Dy QuickDraw, if tnis Is your first exposure to tnree-dlmenslonai 
graphics, you will find Graf3D's standard procedures and functions a great help 
In producing visually exciting graphs, charts, and drawings, if you are familiar 
with Applegraphlcs for the Apple II, you will feel right at home with Graf3D's 
use Of real varlaDles and world coordinates. 

with three-dimensional graphics you can present objects In true perspective, 
which will evoke for users their everyday environment. Graf3D helps you 
represent complex business Information plctorlaily; for example, a manager can 
see important relationships among sales, profits, and advertising dollars in a 
three-dimensional graph. 

You may be Interested in a more theoretical discussion of three-dimensional 
graphics, including an explanation of some of the basic concepts of Graf3D, 
such as the viewing pyramid. A good. Illustrated discussion appears in the 
section on three-dimensional computer graphics in Principles of Interactive 
Computer Grapnics by William M. Newman and Robert F. Sproull (New York: 
McGraw-Hill, 1973). 

E.12.1 How Graf3D Is Related to QuickDraw 

Graf3D is a Pascal unit that makes the QuickDraw calls necessary to produce 
three-dimensional graphics. Ii provides you with an easy-to-use real number 
interface to QuickDraw's integer coordinates. You could, of course, write 
your own QuickDraw calls to perform the same functions Graf3D provides for 
you, but that would be a little like going to the trouble of writing your own 
compiler. 

E.12.2 Features of Graf3D 

• A camera-eye t//eui This allows you to set the point of view from which 
the observer sees the object Independently from the coordinates of the 
Object Itself. The camera is set up with the Viewport, LookAt, and 
view Angle procedures. You can set the focal length of the camera as If 
you had a choice of telepnoto, wide angle, or normal lenses. 

• Thiee-almenslmal clipping tv a tjue pyramid. The apex of the pyramid Is 
at the point of the camera eye, and trie base of the pyramid Is equivalent 
to the viewport. When you use the Cllp3D function, only objects forward 
of the camera eye and within the pyramid are displayed on the screen. 

• Two-aimenslonal point ana line capability using real coordinates. Graf 3D 
provides commands corresponding to the QuickDraw commands but using 
real coordinates instead of integers, with real coordinates you have a 
larger dynamic range for graphics calculations; with Integer coordinates 
you get faster drawing time. For reals, the range is 

i.a x 10"^^ to 3.a X 10^^ 
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• Two-cflmenslonal or mree-ciinyenslonal rotation. You can rotate an object 
along any or all axes simultaneously, using the Pitch, Yaw, and Roll 
procedures. 

• Translation and scaling of otjjects In one or more axes simultaneously. 
Translation means movement anywhere in three-dimensional space. Scaling 
means shrinking or expanding. 

E.12.3 Graf3D Data Types 

Graf3D declares and uses the following data types: 

Polnt3D: A Polnt3D contains three real numoer coordinates: x, y, and z. 

Graf3D uses x, y, and z for real number coordinates to distinguish 
between the h and v Integer screen coordinates in QuickDraw. 

Polht2Q A Polnt2D is just like a Polnt3D but contains only x and y 
coordinates. 

XfMatrlx The XfMatrix is a 4x4 matrix of real values, used to hold a 

transformation equation. Each transforming routine alters this 
matrix so that It contains the concatenated effects of all 
transformations applied. 

Poit3DPtr: A Port3DPtr Is a pointer to a Port3D. 

Port3D: A Port3D contains all the state variables needed to map real 

number coordinates Into Integer screen coordinates. They are as 
follows: 

GPort: a pointer to the grafPort associated with this Port3D. 

viewRect: the viewing rectangle within the grafPort; the base of the 
viewing pyramid. 

xLeft, yTop, xRlght, yBottom: world coordinates corresponding to 
the vlewRect 

pen: three-dimensional pen location. 

penPrime: the pen location transformed by the xForm matrix. 

eye: three-dimensional viewpoint location established by ViewAngle. 

hSize, vSIze: half -width and half-height of the viewRect In screen 
coordinates. 

hCenter, vCenter: center of the viewRect in screen coordinates. 

xCotan, yCotan: viewing cotangents set up by ViewAngle, used by 
Clip3D. 

ident a boolean that allows the transformation to be skipped when 
when xForm is an Identity matrix. 

xForm: a 4x4 matrix that holds the net result of all transformations. 
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E.12.4 Graf3D Procedures and Functions 

The following procedures and functions are provided In Graf3D. 

Procedure Open30Port(port: Port30Ptr); 

Open3DPort Initializes all the fields of a Port3D to their defaults^ and makes 
that Port3D the current one. Gport is set to the currently open grafPort. 
The defaults established are: 

tri8Port3D:=port; 

port * . GPort : = thePort; 

ViewPort( thePort \ portRect ); 

ilTH thePort\pGrtRect DO LookAt( left, top, right, bottom); 

vlewAngle(O); 

Identity; 

riOVeTQ3D(0, 0, 0); 

Procedure S8tPort30(port: Port3DPtr); 

SetPort3D makes port the current Port3D and calls setPort for that Port3D's 
associated grafPort. SetPort3D allows an application to use more than one 
Port3D and switch between them. 

Procedure GetPort3D(var port: Port3DPtr); 

GetPort3D returns a pointer to the current Pon3D. This procedure Is useful 
when you are using several Port3Ds and want to save and restore the current 
one. 

Procedure rioveTo2D(x,y: real); Procedure MoveTo30()cy^z: real); 
Procedure hove2D(dx,dy: real); Procedure riove3D(dx,dy,dz: real); 

These procedures move the pen In two or three dimensions without drawing 
lines. The real number coordinates are transformed by the xForm matrix and 
projected onto flat screen coordinates; then Graf3D calls QuickDraw's MoveTo 
procedure with the result. 

Procedure LlneTo2D(>cy: real); Procedure LineTo3D()cy,z: real); 
Procedure Llne2D(d)cc^: real); Procedure Llne3D(dx,dy,dz: real); 

These procedures draw two- and three-dimensional lines from the current pen 
location. LlneToZD and LlneZD stay on the same z-plane. The real number 
coordinates are first transformed by the xForm matrix, then clipped to the 
viewing pyramid, then projected onto the flat screen coordinates and drawn by 
calling QuickDraw's LlneTo procedure. 
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Function Cllp30(srcl.src2: Point3D; var dstl.dstZ: Point): boolean; 

Clip3D Clips a three-dimensional line segment to the viewing pyramid and 
returns the clipped line projected onto screen coordinates. Clip3D returns 
true if any part of the line is visible. If no part of the line is within the 
viewing pyramid^ Clip3D returns false. 

Procedure SetPt30(var pt30: Polnt3D; Ky,zi real); 

setPt3D assigns three real numbers to a Point3D. 

Procedure SetPt20(var pt2D: Point2D; x,y: real); 

SetPtZD assigns two real numbers to a Point2D. 

E.12A1 Setting Up the Camera (Viewports LookAt and VlewAngle) 

Procedures Viewport LookAt and viewAngie position the image in the 
grafPort, aim the camera, and choose the lens focal length in order to map 
three-dimensional coordinates onto the flat screen space. These procedures 
may be called in any order. 

Procedure ViewPort(r: Rect); 

Viewport specifies where to put the image in the grafPort. The Viewport 
rectangle is in Integer QuickDraw coordinates, and tells where to map the 
LookAt coordinates. 

Procedure LookAt(left, top, rights bottom: real); 

LookAt specifies the real number x and y coordinates corresponding to the 
vlewRect 

Procedure VleifAngle(angle: real); 

ViewAngie controls the amount of perspective by specifying the horizontal 
angle (in degrees) subtended ti)/ the viewing pyramid. Typical viewing angles 
are 0** (no perspective), 10* (telephoto lens), 25" (normal perspective of the 
human eye), and 80" (wide angle lens)L 

E.13A2 The Transformation Matrix 

The transformation matrix allows you to impose a coordinate transformation 
between the coordinates you plot and the viewing coordinates. Each of the 
transformation procedures concatenates a cumulative transformation onto the 
)^omn matrix, subsequent lines drawn are first transformed ti^ the )tf=^oim 
matrix, then promoted onto the screen as specified by ViewPort, LookAt, and 
ViewAngie. 

Procedure Identity; 

Identity resets the transformation matrix to an identity matrix. 
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Procedure scale(xFaotor.yFactor.zFactor: real); 

Scale modifies the transformation matrix so as to shrink or expand Dy xFactor, 
yFactOL and zFactor. For example^ Scale(2.0^.0^.0) will make everything 
come out twice as big when you draw. 

Procedure Translate(dx,dy^dz: real); 

Translate modifies the transformation matrix so as to displace by d)cdy^. 

Procedure Pitch(xftngle: real); 

Pitch modifies the transformation matrix so as to rotate x/Nngle degrees 
around the x axis. A positive angle rotates clockwise when looking at the 
origin from positive x 

Procedure Ya«»(yAngle: real); 

Yaw modifies the transformation matrix so as to rotate yAngle degrees around 
the y axis. A positive angle rotates clockwise when looking at the origin 
from positive y. 

Procedure RolKzAngle: real); 

Roll modifies the transformation matrix so as to rotate zAngle degrees around 
the z axis. A positive angle rotates clockwise when looking at the origin 
from positive z. 

Procedure Ske«(zAngle: real); 

Skew modifies the transformation matrix so as to skew zAngle degrees 
around the z axis. Skew only changes the x coordinate; the result is much 
like the slant QuickDraw gives to Italic characters. (Skew(15.o) makes a 
reasonable italic.) A positive angle rotates clockwise when looking at the 
origin from positive z. 

Procedure TrensFonn(src: Point3D; var dst: Polnt30); 

Transform applies the xFoim matrix to src and returns the result as dst If 
the transformation matrix is Identity, dst will be the same as src. 
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E.13 Quickoraw interface 

UNIT QuickDraw; 

{ Copyright 1983 Apple Conputer Inc. } 
INTERFACE 



CONST srccopy 


= 0; 


srcor 


= 1; 


srcXor 


= 2; 


srcBic 


= 3; 


notsrccopy 


= 4; 


notsrcor 


= 5; 


notsrcxor 


= 6; 


notSrcBic 


= 7; 


patCopy 


= 8; 


patOr 


= 9; 


patxor 


= 10; 


patBic 


= 11; 


notPatCopy 


= 12; 


notPatOr 


= 13; 


notPatXor 


= 14; 


notPatBlc 


= 15; 


{ QuickDraw color 


separat 


normalBlt 


= 0; 


InverseBlt 


= 1; 


redBlt 


= 4; 


greenBit 


= 3; 


blueBit 


= 2; 


cyanBit 


= 8; 


magentaBlt 


= 7; 


yellowBit 


= 6; 


blackBit 


= 5; 


blackColor 


= 33; 


whiteColor 


= 30; 


redColor 


= 205; 


greenColor 


= 341; 


blueColor 


= 409; 


cyanColor 


= 273; 


magentaColor 


= 137; 


yellowColor 


= 69; 


picLParen 


= 0; 


picRParen 


= 1; 



{ the 16 transfer modes } 



{ normal screen mapping 
{ inverse screen ineiDplng 
{ RGB additive mapping } 



{ CMYBk sudtractive mapping } 



{ colors expressed In these mappings } 



{ standard picture comments } 
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OOByte 


-128.. 127; 


QOPtr 


^OOByte; { blind pointer } 


QDHandle = 


'^ODPtr; { blind handle } 


Str255 


String[2553; 


Pattern = 


PACKED ARRAY[0..7] OF 0..255; 


Bitsie 


ARRAY [0.. 15) OF INTEGER; 


VHSelect = 


(V,h); 


GrafVerb = 


(frame, paint, erase, invert, fill); 


Styleltem = 


(bold, Italic, underline, outline, shadow, condense. 




extend); 


style 


SET OF Styleltent- 


Fontlnfo = 


RECORD 




ascent: INTEGER; 




descent: INTEGER; 




widMax: INTEGER; 




leading: INTEGER; 




END; 


Point = RECORD CASE INTEGER OF 


0: 


(v: INTEGER; 


h: 


INTEGER); 



1: (Vh: ARRAY [VHSelect] OF INTEGER); 
END; 

Rect = RECORD CASE INTEGER OF 



0: (top: 
left: 
bottom: 
right: 



INTEGER; 
INTEGER; 
INTEGER; 
INTEGER); 



1: (topLeft: Point; 
botRight: Point); 
END; 
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BitHap = 


RECORD 




baseAddr: OOPtr; 




rowBytes: INTEGER; 




bounds: Rect; 




END; 


cursor = 


RECORD 




data: Bitsl6; 




mask: Bitsl6; 




hotSpot: Point; 




END; 


Penstate 


= RECORD 




pnLoc: Point; 




pnsize: Point; 




pnMode: INTEGER; 




pnPat: Pattern; 




END; 


PolyHandle = "PolyPtr; 


PolyPtr 


= ^Polygon; 


Polygon 


= RECORD 




pOlySize: INTEGER; 




polyBBox: Rect; 




polyPoints: ARRAY[0..0] OF Point; 




END; 


RgnHandle = "RgnPtr; 


RgnPtr 


= "Region; 


Region 


= RECORD 



rgnSize: INTEGER; { rgnSize = 10 for rectangular } 

rgnBBox: Rect; 

{ plus more data if not rectangular } 

END; 



PlcHandle = "^PlcPtr; 
PicPtr = "Picture; 
Picture = RECORD 

picSize: INTEGER; 

picFrame: Rect; 

{ plus byte codes for picture content } 
END; 
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QDProcsPtr = "QDProcs; 




QDProcS » RECORD 




textProc: 


QDPtr; 


llneProc: 


QDPtr; 


rectProc: 


ODPtr; 


rRectProc: 


QDPtr; 


ovalProc: 


ODPtr; 


arcProc: 


QDPtr; 


polyProc: 


QDPtr; 


rgnProc: 


QDPtr; 


DitsProc: 


ODPtr; 


comnentProc: 


ODPtr; 


txMeasProc: 


ODPtr; 


getPlcProc: 


QDPtr; 


putPlcProc: 


ODPtr; 


END; 




GrafPtr = "GrafPort; 




GrafPort = RECORD 




device: 


INTEGER; 


portBits: 


Bltnap; 


portRect: 


Rect; 


visRgn: 


RgnHandle; 


ClipRgn: 


RgnHandle; 


bkPat: 


Pattern; 


flllPat: 


Pattenv 


pnLOC: 


Point; 


pnsize: 


Point; 


pnhode: 


INTEGER; 


pnPat: 


Pattera- 


pnVls: 


INTEGER; 


txFont: 


INTEGER; 


txFace: 


Style; 


txhode: 


INTEGER; 


txSlze: 


INTEGER; 


spExtra: 


Longint; 


fgColor: 


Longint; 


dkColor: 


Longint; 


colrBit: 


INTEGER; 


patStretch: 


INTEGER; 


picSave: 


QDHandle; 


rgnSave: 


OOHandle; 
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polySave: 


QOHandle; 




grafProcs: 


ODProcsPtr; 




END; 




VAR thePort: 


GrafPtr; 




white: 


Pattern; 




black: 


Pattern- 




gray: 


Pattern; 




ItGray: 


Pattern; 




dkGray: 


Pattern; 




arrow: 


Cursor; 




screenBits: 


BitMap; 




randSeed: 


Longint; 





{ GrafPort Routines } 



PROCEDURE InitGraf 


(globalPtr: QDPtr); 


PROCEDURE OpenPort 


(port: GrafPtr); 


PROCEDURE initPort 


(port: GrafPtr); 


PROCEDURE ClosePort 


(port: GrafPtr); 


PROCEDURE SetPort 


(port: GrafPtr); 


PROCEDURE GetPort 


(VAR port: GrafPtr); 


PROCEDURE GrafDevlce 


(device: INTEGER); 


PROCEDURE SetPortBltS 


(Dm: BitMap); 


PROCEDURE PortSlze 


( width, height : INTEGER); 


PROCEDURE MovePortTo 


( lef tGlobal, topGlobal : INTEGER); 


PROCEDURE SetOrlgln 


(h,v: INTEGER); 


PROCEDURE SetCllp 


(rgn: RgnHandle); 


PROCEDURE GetClip 


(rgrt: RgnHandle); 


PROCEDURE ClipRect 


(r: Rect); 


PROCEDURE BackPat 


(pat: Pattern); 



{ Cursor Routines } 

PROCEDURE Inltcursor; 
PROCEDURE SetCursor(crsr: Cursor); 
PROCEDURE HideCursor; 
PROCEDURE ShowCursor; 
PROCEDURE ODscureCursor; 
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{ Line Routines } 

PROCEDURE HidePen; 
PROCEDURE ShOWPen; 

PROCEDURE GetPen (VAR pt: Point); 
PROCEDURE GetPenState(VAR pnState: PenState); 
PROCEDURE SetPenState(pnstate: PenState); 

PROCEDURE Pensize (width, height: INTEGER); 

PROCEDURE Penriode (mode: integer); 

PROCEDURE PenPat (pat: Pattern); 
PROCEDURE PenNormal; 

PROCEDURE MoveTo (h,v: INTEGER); 

PROCEDURE Move (dh.dv: INTEGER); 

PROCEDURE LineTo (h,v: INTEGER); 

PROCEDURE Line (dh^dv: INTEGER); 



{ Text Routines } 



PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 



TextFont 

TextFace 

Textriode 

TextSize 

SpaceExtra 

DrawChar 

Drawstring 

DrawText 

CharHidth 

Strlngwidth 

Textllldth 



PROCEDURE GetFontlnfo 



(font: INTEGER); 

(face: style); 

(mode: INTEGER); 

(size: INTEGER); 

(extra: Longint); 

(ch: char); 

(s: Str255); 

(textBuf: QOPtr; flrstByte.dyteCount: INTEGER); 

(ch: CHAR): INTEGER; 

(S: Str255): INTEGER; 

(textBuf: QOPtr; firstSyte^byteCount: INTEGER): 

INTEGER; 
(VAR info: Fontlnfo); 



{ Point Calculations } 



PROCEDURE AddPt 


PROCEDURE SubPt 


PROCEDURE SetPt 


FUNCTION EqualPt 


PROCEDURE ScalePt 


PROCEDURE MapPt 


PROCEDURE LocalToGlOdal 


PROCEDURE GlobalToLocal 



(src: Point; VAR dst: Point); 
(src: Point; VAR dst: Point); 
(VAR pt: Point; h,v: INTEGER); 
(ptl^ptZ: Point): BOOLEAN; 
(VAR pt: Point; 
(VAR pt: Point; 
(VAR pt: Point); 
(VAR pt: Point); 



froii«ect,toReot: Rect); 
fron«ect,toRect: Rect); 
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{ Rectangle Calculations } 



PROCEDURE 
FUNCTION 
FUNCTION 
PROCEDURE 



SetRect 
EqualRect 
EmptyRect 
OffsetRect 



PROCEDURE MapRect 
PROCEDURE InsetRect 
FUNcnoN sectRect 
PROCEDURE UnionRect 
FUNCTION PtinRect 
PROCEDURE Pt2Rect 



(VAR r; Rect; left. top. right. t)ottom: INTEGER); 

(recti. rect2: Rect): BOOLEAN; 

(r: Rect): BOOLEAN; 

(VAR r: Rect; clh.clv: INTEGER); 

(VAR r: Rect; f rofHRect. toRect : Rect); 

(VAR r: Rect; Clh.Clv: INTEGER); 

(srcl.src2: Rect; VAR dstRect: Rect): BOaEAN; 

(srci.src2: Rect; VAR dstRect: Rect); 

(pt: Point; r: Rect): BOOLEAN; 

(ptl.pt2: Point; VAR dstRect: Rect); 



{ Graphical Operations on Rectangles } 



PROCEDURE FraroeRect (r: 
PROCEDURE PaintRect (r: 
PROCEDURE EraseRect (r: 
PROCEDURE InvertRect (r: 
PROCEDURE FlllRect (r: 



Rect); 
Rect); 
Rect); 
Rect); 
Rect; pat: Pattern); 



{ Rouncff^ect Routines } 

PROCEDURE FraraeRoundRect (r: Rect; 
PROCEDURE PalntRoundRect (r: Rect; 
PROCEDURE EraseRoundRect (r: Rect; 
PROCEDURE invertRoundRect (r: Rect; 
PROCEDURE FlllRoundRect (r: Rect; 



0V«d.0VHt: INTEGER); 
OVUaovHt: INTEGER); 
OVl!d.OVHt: INTEGER); 
OVlfctOVHt: INTEGER); 
ovlld.ovHt: INTEGER; pat: Pattern); 



{ Oval Routines } 

PROCEDURE Frameoval (r: Rect); 

PROCEDURE Palntoval (r: Rect); 

PROCEDURE Eraiseoval (r: Rect); 

PROCEDURE invertOval (r: Rect); 

PROCEDURE Fllioval (r: Rect; pat: Pattern); 



{ Arc Routines } 



PROCEDURE FraroeArc 
PROCEDURE PalntArc 
PROCEDURE EraseArc 



(r: Rect; 
(r: Rect; 
(r: Rect; 
PROCEDURE invertArc (r: Rect; 



startAngle.arcAngle: INTEGER); 

startAngle.arcAngle: INTEGER); 

StartAngle.arcAngle: INTEGER); 

StartAngle.arcAngle: INTEGER); 
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PROCEDURE FlllArc (r: Rect; startAngle^arcAngle: INTEGER; pat: 

Pattern) * 
PROCEDURE PtToAngle (r: Rect; 'pt: Point; VAR angle: INTEGER); 



{ Polygon Routines } 



FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 



OpenPoly: 

ClosePoly; 

KillPoly 

OffsetPoly 

riapPoly 

FramePoly 

PaintPoly 

ErasePoly 

invertPoly 

FillPoly 



PolyHandle; 

(poly: PolyHandle); 

(poly: PolyHandle; dh^dv: INTEGER); 

(poly: PolyHandle; fron«ect,toRect: Rect); 

(poly: PolyHandle); 

(poly: PolyHandle); 

(poly: PolyHandle); 

(poly: PolyHandle); 

(poly: PolyHandle; pat: Pattern); 



{ Region Calculations } 



FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 

FUNCTION 



NewRgn: RgnHandle; 

DisposeRgn(rgn: RgnHandle); 

CopyRgn (srcRgn^dstRgn: RgnHandle); 

SetEnptyRgn(rgn: RgnHandle); 

SetRectRgn(rgn: RgnHandle; left, top, right, bottom: INTEGER); 



RectRgn 

OpenRgn; 

CloseRgn 



(rgn: RgnHandle; r: Rect); 



(dstRgn: RgnHandle); 
OffsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 
MapRgn (rgn: RgnHandle; fron«ect,toRect: 
InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 

(srcRgnA,srcRgnB, dstRgn: RgnHandle); 

(srcRgnA, srcRgnB, dstRgn : 

(srcRgnA, srcRgnB, dstRgn : 

(srcRgnA, srcRgnB, dstRgn : 

(rgnA,rgnB: Rgn^tendle): BOOLEAN; 

(rgn: RgnHandle): BOOLEAN; 

(pt: Point; rgn: RgnHandle): BOOLEAN; 

(r: Rect; rgn: RgnHandle): BOOLEAN; 



Rect); 



SectRgn 

UnionRgn 

DiffRgn 

XorRgn 

EqualRgn 

EnptyRgn 

PtInRgn 

RectlnRgn 



RgnHandle); 
RgnHandle); 
RgnHandle); 



{ Graphical Operations on Regions } 



PROCEDURE FrameRgn 
PROCEDURE PaintRgn 
PROCEDURE EraseRgn 



(rgn: RgnHandle); 
(rgn: RgnHandle); 
(rgn: RgnHandle); 
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PROCEDURE invertRgn (rgn: RgnHandle); 

PROCEDURE FlllRgn (rgn: RgnHandle; pat: Pattern); 



{ Graphical Operations on Bltfiaps } 

PROCEDURE ScrollRectCdstReot: Rect; dh^dv: INTEGER; updateRgn: 

rgnHandle); 
PROCEDURE CopyBltS (srcBlts^dStBitS: BltMap; 

srcRect^dstRect: Rect; 

mode: INTEGER; 

maskRgn: RgnHandle); 

{ Picture Routines ) 

FUNCTION OpenPicture(picFrame: Rect): PicHandle; 

PROCEDURE ClosePicture; 

PROCEDURE DrawPlcture(myPicture: PicHandle; dstRect: Rect); 

PROCEDURE PicConinent(kind.dataSi2e: INTEGER; dataHandle: QDHandle); 

PROCEDURE KillPictureCmyPicture: PicHandle); 



{ The Bottleneck Interface: } 



PROCEDURE 
PROCEDURE 

PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 

PROCEDURE 
PROCEDURE 
PROCEDURE 

PROCEDURE 
FUNCTION 



PROCEDURE 
PROCEDURE 



SetStdProcs(VAR procs: QDProcs); 

StdText (count: INTEGER; textAddr: QDPtr; numer^ denom: 

Point); 
StdLine (newPt: Point); 
StdRect (verb: Graf Verb; r: Rect); 
StdRRect (verb: Graf Verb; r: Rect; ovIfcLovHt: INTEGER); 
StdOval (verb: Graf Verb; r: Rect); 
StdArc (verb: GrafVerb; r: Rect; startAngle,arcAngle: 

INTEGER); 
StdPoly (verb: GrafVerb; poly: PolyHandle); 
StdRgn (verb: GrafVerb; rgn: Rgn^tendle); 
StdBits (VAR srcBits: BitMap; VAR srcRect^ dstRect: Rect; 

mode: INTEGER; maskRgn: RgnHandle); 
StdComnent (kind^dataSize: INTEGER; dataHandle: QDHandle); 
StdTxrieas (count: INTEGER; textAddr: QDPtr; 

VAR numer^denom: Point; 

VAR info: Fontlnfo): INTEGER; 
StdGetPic (dataPtr: QDPtr; byteCount: INTEGER); 
StdPutPic (dataPtr: QDPtr; byteCount: INTEGER); 
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{ ttlsc Utility Routines } 

FUNCTION GetPlxel (h,v: INTEGER): BOOLEAN; 
FUNCnON Random: INTEGERS- 
PROCEDURE Stuff Hex (thlngptr: ODPtr; s:Str255); 
PROCEDURE ForeColor (color: Longint); 
PROCEDURE Backcoldr (color: Longint); 
PROCEDURE COlorBlt (whlchBlt: INTEGER); 

E.13.1 Graf30 Interface 

{$s Graf } 

UNIT Graf 30; 

{ three-dimensional graphics routines layered on top of QuickDraw } 
INTERFACE 

USES {1!U QD/QuickDra».OBO } OuickDraw; 
CONST radConst«57. 29578; 



TYPE Point30»REC0R0 

x: REAL; 
y: REAL; 
Z: REAL; 
END; 


Point20«REC0R0 

x: REAL; 
y: REAL; 
END; 



Xf Matrix = ARRAY [0 . . 3, . . 3] OF REAL; 
Port3DPtr • "PortJD; 
Port3D = RECORD 

GPort: GrafPtr; 

viewRect: Rect; 

xLeft^yTop^xRlght^yBottom: REAL; 

pen^penPrime^eye; Polnt3D; 

hSize^vSize: REAL; 

hcenter.vcenter: REAL; 

xCotan^yCotan: REAL; 

Ident: BOOLEAN; 

xForm: Xf Matrix; 
END; 
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VAR tnePort30: Port30Ptr; 



PROCEDURE 0pen3DPort 
PROCEDURE SetPort30 
PROCEDURE GetPort30 



(port: Port3DPtr); 
(port: Port30Ptr); 
(VAR port: Port30Ptr); 



PROCEDURE MoveTo20(x,y: REAL); 

PROCEDURE LineT02D(>cy: REAL); 

PROCEDURE riove2D(clx,dy: REAL); 

PROCEDURE Line2D(cl>cdy: REAL); 



PROCEDURE H0VeT03D(x,y^Z: REAL); 
PROCEDURE LineT03D(>cy.Z: REAL); 
PROCEDURE riove30(cl>cdy.dz: REAL); 
PROCEDURE Line3D(dX,dy.dz: REAL); 



PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCnON 



Viewport 

LOOkAt 

ViewAngle 

Identity; 

Scale 

Translate 

Pitch 

Yaw 

Roll 

Skew 

TransForm 

Clip30 



PROCEDURE SetPt30 
PROCEDURE SetPtZO 



(r: Rect); 

( lef t^ top^ rights Dottom : REAL ); 

(angle: REAL); 

(xFactor^yFactor^zFactor: REAL); 

(d)cdy,dz: REAL); 

(xAngle: REAL); 

(yAngle: REAL); 

(zAngle: REAL); 

(zAngle: REAL); 

(src: Point30; VAR dst: Polnt3D); 

(srcl^sro2: PointSO; VAR dstl.dst2: POINT); 

BOOLEAN; 

(VAR pt3D: Point3D; )cy.Z: REAL); 
(VAR pt20: Point2D; )^y: REAL); 
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E.U QiiickOraw Sample Programs 

This section provides listings of two sample programs that are Included with 
the workshop software. 

E.14.1 cpsample 

The program QDSarnple (In the file QDA30Sample.TEXT) demonstrates 
different things that QuickDraw can da Its output Is shown In Figure E-26, 



Look Mi'hat you con dra»^ vi^ith QuickOroM^ 



Text 

Bold 

Italic 
Underline 




Rectangles 




RoundRects 




Bit Images 



m 



l/edges 



M 





» 



Polygons 

"7 




Regions 



/Arbitrary Clipp 
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Ofh !!•»•#»■»»■ r\\r^n\nrt n^nt'irtj 



Glials 




Figure E-26 
QOSampie 

The file QD/M/ODSamplaTEXT is an exec file that can be used to rebuild 
this sample program. Disregard any warning messages from the linker atxxjt 
name conflicts. 
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PROGRAM QOSanple; 

{ Sample program illlustrating the use of QuickDraw. } 

USES {$U 0O/0uickDra«.OBJ } QuickDraw, 
{$U QO/QDSupport.OBJ } QOSupport; 

TYPE ICOnOata = ARRAY[0.. 95] OF INTEGER; 

VARheapBuf: array [0..10000] OF INTEGER; 
myPort: Graf Port; 
icons: ARRAY[o..5) OF Iconoata; 

FUNCTION HeapFull(hz: QOPtr; DytesNeeded: INTEGER): INTEGER; 

{ this function will be called if the heapZone runs out of space } 

BEGIN 

WRITELNCThe heap is full. The program must now terminate! '); 

Halt; 
END; 

PROCEDURE Initlcons; 

{Manually stuff some icons. Normally we would read them from a file } 

BEGIN 



{ Lisa } 

StuffHex(aicons[Oy 
StuffHex(aicons[0, 12 



, •OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOIFFFFFFFFC ); 
, • 00600000000601800000000B0600000000130FFFFFFFFFA3 ' ); 



Stuff Hex(aicons[0^ 2k\ ' 18000000004311FFFFF00023120000080F231200000BF923 ' 

StuffHex(aicons[0.36 

Stuf f Hex(aicons[ 0, 48 

Stuf f Hex(aicons[ 0^ 60 

StuffHex(aicons[0^ 72' 

StuffHex(aicons[0, 84 



^ 



•12000d080F23120000080023120000080023120000080F23 
• 1200000BF923120000080F2312000008002311FFFFF00023 ' 
• 08000000004307FFFFFFFFA30100000000260FFFFFFFFE2C ' 
' 18000000013832AAAAA8A9F0655555515380C2AAAA82A580 * ); 
' 800000000980FFFFFFFFF300800000001600FFFFFFFFFCOO ' ); 



{ Printer } 

Stuff Hex(aiconsr 1, 0],' 000000000000000000000000000000000000000000000000 • >; 
StUffHex(aiconstl, 12], •00000000000000007FFFFF00000080000280000111514440' ); 
StUffHex(aicons[l^ 24L •0002000008400004454510400004000017C00004A5151000' ); 
StUffHex(aicons[l, 36], * 0004000010000004A545t0000004000017FEOOF4A5151003' ); 
Stuff Hex(aicons[ 1^ 48], ' 01840000i3870327FFFFF10F06400000021B0CFFFFFFFC37 ' ); 
StuffHex(aicons[l, 60], * 18000000006B3000000000077FFFFFFFFFABC00000000356' ); 
StUffHex(aicons[l^ 72L '8000000001AC87F000000158841000CCC1B087FOOOCCC160* ); 
StuffHex(aicons[l,84L'8000000001C0C000000003807FFFFFFFFF0007800001E000'); 
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{ Trash Can } 
StuffHex(aicons[2. 
Stuf fHex(alcons[2. 12 
Stuf fHex(aicons[2. 24 
Stuff Hex(aicons[2. 36 
Stuf fHex(aicons[2, 48 
StuffHex(aicons[2,60 
StuffHex(aicons[2.72 
StuffHex(aicons[2.84 

{ tray } 

StuffHex(aicons[3^ 

StuffHex(aicons[3.12 

StuffHex(aicons(3,24 

StuffHex(aicons[3.36 

StuffHex(aicons(3, 48 

StuffHex(aicons[3,60 

StuffHex(aiconsl3.72 

StuffHex(aicons[3.84 

{ File Cabinet } 
StuffHex(aicons[4^ 
StuffHex(aicons[4,i2 
stuff Hex(aicons[4, 24 
StuffHex(aicons[4,36 
StuffHex(aicons[4,48 
Stuff Hex(aicons[4. 60 
StuffHex(aicons[4,72 
StuffHex(aicons[4.84 

{ drawer ) 

StuffHex(aicons[5, 
Stuff Hex(aicons[5, 12 
StuffHex(aicons[5,24 
StuffHex(aicons[5.36 
Stuff Hex(aicons[5, 48 
StuffHex(aicons[5.60 
StuffHex(aicons[5.72 
StuffHex(aicons[5.84 

END; 



, '000001FCOOOOOOOOOE0600000000300300000000C0918000' ); 
, •00013849800000026C4980000004C0930000000861260000' ); 
, •0010064FE0000031199830000020E6301800002418E00800' ); 
, '0033E3801C0000180E002COOOOOFF801CC0000047FFEOCOO* ); 
. •000500004C000005259A4C000005250A4C00000525FA4COO' ); 
, *000524024C00000524924C00600524924C0090E524924C7C' ); 
, •932524924C82A44524924001C88524924CF10C4524924C09' ); 
. •0784249258E70003049233100000EOOOE40800001FFFC3FO' ); 



, 'OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO' ); 
. '0000000000000000000000000000000000000007FFFFFFFO' ); 
, 'OOOE00000018001A00000038005600000078006A00000008' ); 
, •00O7FFFFFFB801AC000003580358000O06B807FC000FFD58' ); 
, '040600180AB80403FFFOOD58040000000AB8040000000058' ); 
. •040000000AB807FFFFFFFD5806ACOOOOOAB8055800000D58' ); 
1. •06BOOOOOOAB807FCOOCFFD70040600180AE00403FFFOOOCO' ); 
. •040000000B80040000000F00040000000E0007FFFFFFFCOO' ); 



. '0007FFFFFC00000800000C00001000001C00002000003400' ); 
. •004000006COOOOFFFFFFD40000800000ACOOOOBFFFFED400' ); 
. •0OA00002AC0000A07F0204OO0OA04102AC0O00A07F02O400' ); 
. •OOA00002ACOOOOA08082040000AOFF82ACOOOOA000020400" ); 
, •OOA00002ACOOOOBFFFFED40000800000ACOOOOBFFFFED400' ); 
. •OOA00002ACOOOOA07F02D40000A04102ACOOOOA07F02D400' ); 
. •OOA00002ACOOOOA08082D40000AOFF82ACOOOOA00002D800' ); 
> •OOA00002B000008FFFFEE00000800000COOOOOFFFFFF8000' ); 



, 'OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO' ); 
. • 000000000000000000000000000000000000000000000000 • ); 
, • 000000000000000000000000000000000000000000000000 ' ); 
. 'OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOIFFFFFFO* ); 
. •0000380000500000680000700000080000D0003FFFFFF1BO' ); 
. •0020000013500020000016B000201FE01D50002010201ABO' ); 
, '00201FE01560002000001AC0002000001580002020101BOO* ); 
. '00203FF01600002000001C00002000001800003FFFFFFOOO' ); 
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PROCEDURE Dra«Icon(«hlChICOah.V: INTEGER); 
VAR srcBlts: BitM^; 

srcRect^dstRect: Rect; 
BEGIN 

srcBlt s . DaseAddr : =aicons [ whichlcon ); 

srcBit s . roieytes : »6; 

SetRect(srcBlts . bounds, 0, 0, 4a, 32); 

srcRect : "SrcBits . bounds; 

dstRect:=srcRect; 

Of f setRect(dstRect, f\, v); 

CopyBlts(srcBits, tnePort" .portBlts, srcRect, dstRect, srcOr, Nil); 

END; 

PROCEDURE DrawStUf f ; 

VAR 1: INTEGER; 
tanpRect: Rect; 
niyPoly: PolyHandle; 
ntyRgn: RgnHandle; 

fiyPattern: Pattern; 

BEGIN 
stuff Hex<amyPattern. ' 8040200002040800 * ); 

tempRect :- tnePort*.portRect; 
CllpRect(teflpRect); 
EraseRoundRectCteijpRect, 30^ 20); 
FraraeRoundRectCteirpRect, 50^ 20); 

{ draw tiK) horizontal lines across tne top } 

MoveTo(0^18); 

LlneTo(7l9,18); 

MoveTo(0,20); 

LlneTo(719,20); 

{ draw divider lines } 

MoveTo(0^ 134); 

LlneT0(719.134); 

MoveTo( 0,248); 

LlneTo(719,248); 

rtoveTo(240,21); 

LlneTo(240,363); 

MoveTo(480,21); 

LineTo(480,363); 
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{ draw title } 

TextFont(O); 

M0VeT0(2ia 14); 

OrawStringCLook iihat you can drav with QuickOra«'); 



{ draw text sanples — 

MoveTo(80^ 34); Dra«»String( ' Text ' ); 

TextFace([bold]); 

MoveTo(70, 55); Ora«Strlng( 'Bold* ); 

TextFace([ Italic]); 

MoveTo(70^ 70); Ora«String( ' Italic ' ); 

TextFace( [ underline ] ); 

MoveTo(70,85); OrawStringC Underline'); 

TextFace( [cxjtline) ); 

MGveTo(70^ 100); Ora*»Str ing( ' Outline ' ); 

TextFace( [ shadow 3 ); 

rioveTo(70, 115); Dra«String( ' Shadow ' ); 

TextFace([]); { restore to normal } 



{ draw line sanples ~ ) 

MoveTo(330,34); DrawString( 'Lines'); 

MoveTo(280,25); Line(160.40); 

PenSize(3,2); 

MoveTo(280, 35); Line(160^ 40); 

PenSi2e(6^ 4); 

MoveTo(280,46); Line(160, 40); 

PenSize(12^8); 
PenPat(gray); 
rioveTo(280,61); Line(160, 40); 
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PenSize(15,10); 
PenPat(inyPattern); 
MoveTo(28a80); Line(16a40); 
PenNormal; 

{ draw rectangle samples } 

MoveTo(560, 34); OrawString< 'Rectangles'); 

SetRect(teiBpRect^ 510, 40^ 570^ 70); 
FrameRect(tenpRect); 

Of f setRect(teirpRect, 25, 15); 
PenSize(3, 2); 
EraseR8Ct(tenpR8Ct); 
FraradRect ( tenpRect ); 

Of f setRect(tenpRect, 25, 15); 
PalntRect ( terapRect ); 

Of f setRectCtempRect, 25, 15); 
PenNormal; 

FlllRect(tefrpRect, gray ); 
FrameRect(teJnpRect); 

Of f setRectCtempRect, 25, 15); 
FillRect(tenpRect, nyPattern); 
FrameRect ( tenpRect ); 

{ draw roundRect samples — } 

MoveTo(70, 148); OrawStringCRoundRects'); 

SetRectCtempRect, 30, 150, 90. 180); 
FrQmoRounclReot(toiBpRoot, 50, 20); 

Of f setRect(teapRect, 25^ 15); 
PenSi2e(3,2); 

EraseRouncRRect(tempRect, 30, 20); 
FrameRoundRect(tempRect, 30, 20); 

Of f setRect(tempRect, 25, 15); 
PaintRoundRect( tenpRect, 30, 20); 
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Of f setRectCtenpRect, 25^ 15); 
PenNormal; 

FillRoundRectCtempRect, 30, 20, gray); 
FrameRoundRect(teiifjRect^ 30, 20); 

Of f setRect(tempRect, 75, 15); 
FillRoundRect(teirpRect, 30, 20, myPattem); 
FrameRoundRect(tempRect^ 30, 20); 

{ draw bit image sanples } 

MoveTo(320, 148); Dra»String( 'Bit Images' ); 

Dra»Icon(0,266,156); 
Dra«»Icon(l,336,156); 
Drawlcon(2,406,156); 
Drai»Icon(3, 266,1%); 
DrawIcon(4, 336, 1%); 
DrawIcon(5, 406,1%); 

{ draw Wedge samples } 

MoveTo(570, 148); DrawString( ' ledges * ); 

SetRect(tenpRect, 520, 153, 655, 243); 
FillArc(ten^3Rect, 135, 65, ckOray ); 
FillArc(tefnpRect, 200, 130, myPattern); 
FillArc(tempRect, 330, 75, gray); 
FranieArc(teinpRect, 135, 270); 
Of f setRect(teinpRect, 20, 0); 
PaintArc(tetrpRect, 45, 90); 



{ draw polygon sanples 



rioveTo(80, 262); DrawString( ' Polygons ' ); 
inyPoly:=OpenPoly; 

MoveTo(30,290); 

LineTo(30,280); 

LineTo(50,265); 

LineTo(90,265); 

LineTo(80,280); 

LineTo(95,290); 

LineTo(30,290); 

ClosePoly; { end of definition } 
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FraroePoly(inyPoly); 

Of f setPolyCmyPoly, 25, 15); 
PenSize(3,2); 
ErasePoly (myPoly ); 
FramePoly (nyPoly ); 

Of f setPolyCmyPoly, 25, 15); 
PaintPoly(myPoly); 

0ffsetPoly(myPoly,25, 15); 
PenNormal; 

FillPoly(myPoly, gray); 
FramePoly(myPoly 



r 



Of f setPolyCmyPoly, 25, 15); 
FlllPoly(rayPoly, tnyPattern); 
FraniePoly (myPoly ); 

KlllPoly(myPoly); 



{ demonstrate region clipping } 

MoveTo(320, 262); OrawString( ' Regions ' ); 

myRgi:=Neirf^gn; 
OpenRgn; 
ShowPen; 

SetRect(tenpRect, 260, 27t), 460, 350); 
FrameRounclRect(tefnpRect, 24, 16); 

HoveTo(275, 335); { define triangular hole } 

LineTo(325,285); 

LineTo(375,335); 

LlneT0(275, 335); 

SetRect(teirpRect,365,277,445,325); { oval hole } 
FranieOval(teinpRect); 



HidePen; 
CloseRgn(myRgn); 

SetClip(myRgn); 



{ end of definition } 
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FOR i:=0 TO 6 DO { draw stuff inside the clip region } 
BEGIN 

MoveTo(26a280+12*i); 

DrawStringC Arbitrary Clipping Regions'); 
END; 

ClipRect(thePort* .portRect); 
DisposeRgn(myRgn); 

{ draw oval samples } 

MoveTo(580, 262); DrawString( ' Ovals ' ); 

SetRect(teirpRect, 510, 264, 570, 294); 
FraraeOval ( tempRect ); 

Of f setRect(tempRect, 25, 15); 
PenSize(3, 2); 
EraseOval(tefnpRect); 
FrameOval ( teni)Rect ); 

Of f setRect(tenpRect, 25, 15); 
PaintOval ( tenfaRect ); 

Of f setRect(tenpRect, 25, 15); 

PenNormal; 

F i 1 lOval ( tempRect, gray ); 

FrameOval(tefflpRect); 

Of f setRectCtempRect, 25, 15); 
FillOval(teinpRect, myPattern); 
FraraeOval ( tenpRect ); 
END; { DrawStuff } 
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BEGIN { main program } 
{ Initializatlcxi - Generic to all applications using QuickDraw } 
QOInit(aheapBuf, aheapBuf[ 10000], aHeapFull); { Must do this once at 

beginning } 
OpenPort(amyPort); 
PaintRect(thePort*.portRect); { Paint grey background } 

Initlcons; 
DrawStuff; 
Tone(2000, 500); { Beep tone of (1/2000)*10'^6 == 500 cycles/sec for 

500 milliseconds } 
ReadLn; { Wait until RETURN entered before terminating program } 
END. 
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E.iaj? Boxes 

The program Boxes (in the file QD/Boxes.TEXT) uses the Graf 3D routines to 
draw random three-dimensional boxes on a grid, as shown in Figure E-27. 




Figure E-27 
Boxes 

The file QD/M/Boxbs.TEXT is an exec file that can be used to rebuild this 
sample program. Disregard any warning messages from the linker about name 
conflicts. 
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PROGRAM Boxes; 

{ Sample program illustrating use of the 6raf30 unit by drawing random 
30 boxes on a grid. } 

USES 

{$U QO/QuickOraw.OBJ } QuickDraw^ 

{$U go/Graf 30. OBJ > Graf 30^ 

{$U Q0/Q0Support.06J > OOSupport. 



CONST boxCount » 15; 


TYPE Box30=REC0RD 




ptl: Point30; 




pt2: Point3D; 




dist: REAL; 


1 


END; 


VAR 




heapBuf: 


ARRAY[0..8192] OF INTEGER; 


GPortl: 


GrafPort; 


GPort2: 


Port3d; 


myPort: 


GrafPtr; 


myPort3D 


: Port30Ptr; 


boxArray 


ARRAY[0. .boxCount) OF Box30; 


nBoxes: 


INTEGER; 


i: 


INTEGER; 



{16k bytes} 



FUNCTION HeapError(hz: QOPtr; bytesNeeded: INTEGER): INTEGER; 
{ this procedure gets called when the heap zone is full } 
BEGIN 
WRITELNCThe heap is full. The program must now terminate! '); 

HALT; 
END; 



FUNCTION Dl9tanoe(ptl^pt2: P0INT3D): REAL; 

VAR dx,dy,d2: REAL; 

BEGIN 

dx:=pt2.X - ptl.X; 

dy:»pt2.Y - ptl.Y; 

dZ:=pt2.Z - ptl.Z; 

Distance :=SQRT(dx«dx ♦ dy*dy ♦ dz*dz); 
END; 
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PROCEDURE HakeBox; 

VAR myBox: Box3D; 

i,j,h,v: INTEGER; 

pl,p2: Point3D; 

myRect : Rect; 

l6SlK6C V I K6Cl; 

BEGIN 
pi .X: "Random mod 70-lS; 
pl.y:=Random mod 70 -10; 
pi. Z: -0.0; 

p2.x:=pl.x -^ 10 * ABS(Random) MOO 30; 
p2.y:=pl.y + 10 * ABS(Random) MOD 45; 
p2.2:=pl.2 ♦ 10 + ABS(Random) MOO 35; 

{ reject twx If it intersects one already In list } 
SetRect(rayRect, ROUND(pl.x), ROUND(pl.y), R0UND(p2.x), R0UN0(p2.y)); 
FOR i:=0 TO nBoxes-1 DO 
BEGIN 
mTH boxArray[i] DO 
SetRect(testRect, ROUND(ptl .x)^ ROUND(ptl .y), 
R0UN0(pt2.x). R0UND(pt2.y)); 
IF SectRect(myRect^testRect,testRect) THEN EXIT(MakeBGx); 
END; 

inyBox.ptl:=pl; 
myBox. pt2:-p2; 

{ calc midpoint of tx)x and its distance from the eye } 

pl.X:=(pl.x ♦ p2.x)/2.0; 

pl.y:=(pl.y * p2.y)/2.0; 

pl.z:=(pl.z * p2.z)/2.0; 

Transform(pl,p2); 

myBox. dist:=0istance(p2,myPort30''. eye); { distance to eye } 

i:=0; 

boxArray[nBoxes].dist:-rayBox.dist; { sentinel } 

WHILE nyBox.dist > l3oxArray[i].dist DO i:=i*l; {insert in order of dist} 
FOR j:-nBoxes DOIfNTO i*l DO boxArray[j]:-tX)xArray[j-l]; 
twxArray [ i ] : =royBo)C 
nBoxes : =nBoxes*l; 
END; 
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PROCEDURE DrawBox(ptl,pt2: Point30); 
{ draws a 30 box with shaded faces. } 
{ only shades correctly in one direction } 
VAR teirpRgn: RgnHandle; 



{ front face, y=yl > 



{ top face, 2-22 } 



BEGIN 
teifpRgn:=Ne«Rgn; 
OpenRgn; 

l1oveTo30(ptl . X, ptl .y, ptl . z); 

LineTo3D(ptl.)^ ptl .y, pt2.2); 

LineTo3D(pt2 . x, pt 1 .y, pt2 . z); 

LineTo30(pt2 . x, ptl .y, ptl . 2); 

LineTo30(ptl .X, ptl .y, ptl .z); 
CloseRgn(telnpRgn); 
FillRgn(telnpRgn, white); 

OpenRgn; 

MoveTo3D(ptl . X, ptl .y, pt2 . 2); 

LineTo3D(ptl . x, pt2 .y, pt2 . z); 

LineTo3D(pt2 . )C pt2 .y, pt2 . z); 

LineTo3D(pt2 . x, ptl .y, pt2 . z); 

LineTo3D(ptl . >g pt 1 .y, pt2 . 2); 
CloseRgn(teinpRgn); 
FillRgn(tempRgn, gray); 



(^aenRgi; 

MoveTo3D(pt2.x,ptl.y,ptl.2); { right face, 

LineTo30(pt2.>(,ptl.y, pt2.2); 

LineTo3D(pt2.x, pt2.y, pt2.z); 

LlneTo30(pt2 . )^ pt2 .y, ptl . z); 

LineTo3D(pt2 . x, ptl .y, ptl .z); 
CloseRgn(tefnpRgn); 
FillRgn(teinpRgn, black); 



x*x2 } 



PenPat( white); 

MoveTo30(pt2 . >^ pt2 .y, pt2 . z); 
LineTo3D(pt2.x, pt2.y, ptl .z); 
LineTo30(pt2.>^ ptl .y, ptl .z); 
PenNormal; 

DisposeRgn(tenpRgn); 

END; 



( outline right > 
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BEGIN { main program } 
{ Initialization - Generic to all applications using QuickDraw } 
QOInit(aheapBuf, aheapBuf [8192], aheapError); { Must do this once at 

begiming ) 

myPort := aCPortl; 
OpenPor t ( myPor t ) ; 
myPort3D := «6Port2; 
0pen30Por t ( myPor t3D ) ; 

ViewPort(myPort".portRect); { put the image in this rect } 

LookAt(-100,75,100,-75); { aim the camera into 3D space } 

\/ieiDAngle(30); { choose lens focal length } 

Identity; Roll(20); Pitch(70); { roll and pitch the plane } 

PenPat( white); 

BackPat (black); 

EraseRect (myPort " . portRect ); 

FOR i:=-10 TO 10 00 
BEGIN 

MoveTo30( i*10, -100, 0); 

LineTo3D(i«10, +100, OX- 
END; 

FOR i:=-10 TO 10 DO 
BEGIN 

MoveTo3D( -100, i*10, 0); 

LineTo3D( +100, i*10, OX- 
END; 

nBoxes:=0; 

REPEAT MakeBox; UNHL nBoxes=boxCount; 
FOR i:=nBoxes-l DOUNTO DO 
DrawBox(boxArray [i ) .ptl, boxArray [ i ] .pt2); 

Tone(2000, 500); {Beep tone of (1/2000)*10*6 == 500 cycles/sec for 

300 milliseconds } 
ReadLn; { Wait until RETURN entered before terminating program } 

END. 
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E.15 QOSuppoit 

The QOSupport unit (in the file QD/QOSupportTEXT) provides the 
initialization that you need to use QuickDraw In the QDlnit procedure, as well 
as procedures for simplified access to mouse tracking, the mouse button^ and 
sound generation, and useful definitions of font numbers. For more detailed 
Information on mouse-handling routines and sounds refer to /Nppendix F, 
Hardware interface. 

UNIT QOSupport; 

INTERFACE 

USES 



{$u QO/Unltstd.OBJ } unitstd. 


{$U OD/UnitHz.OBJ 


} UnitHz, 


{$U QO/Hard«are.nRi } Hard«iare, 


{$U QO/Fontmgr.OBJ > Fontingr, 


{$U QO/QuickOraw.OBJ } QuickDraw; 


CONST 

/ 


- Cr%r\'¥ Kh n 


...t.^-..^ » 


I 


rOnX NlAiiJCXd / 


FTllelZ 


= 4; 


{proportional} 


FTilelS 


= 5; 


{proportional} 


FTile24 


= 6; 


{proportional} 


FPlSTlle 


= 7; 


{Monospaced - 8 lines/inch & 15 chars/inch} 


FPlZTlle 


= 8; 


{Monospaced - 6 lines/inch & 12 chars/inch} 


FPlOTile 


= 9; 


{Monospaced - 6 lines/inch & 10 chars/inch} 


FCentl2 


= 10; 


{proportional} 


FCentlS 


= 11; 


{proportional 


FCent24 


= 12; 


{proportional 


FP12Cent 


= 13; 


{Monospaced - 6 lines/inch & 12 chars/inch 


FPlOCent 


= 14; 


{Monospaced - 6 lines/inch & 10 chars/inch} 


FP20Tile 


= 19; 


{Monospaced} 
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PROCEDURE QOInit(startPtr, lifnitPtr: gOPtr; ErrorProc: QOPtr); 
{ OOInit: Initializes QuickDraw unit by setting up its heap 

zone, global vars, cursor, and the Font Manager it 

calls on. } 

PROCEDURE GetMouse(VAR pt: Point); 

{ GetMouse: Returns the current mouse location in the local 
coordinates of the current grafPort. } 

FUNCTION HouseButton: BOOLEAN; 

{ MouseButton: Returns TRUE if the mouse button is currently held 
down, otherwise FALSE. } 

PROCEDURE Tone(i»aveLength, duration: Longint); 

{ Tone: Produces a square wave tone of the specified 

wavelength (microseconds) for the specified duration 

(milliseconds). } 
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E16 Glossary 

bit ifnage: A collecticNi of bits in memory that have a rectilinear represen- 
tatioa The Lisa screen is a visible bit image. 

bitmap: A pointer to a bit image, the row width of that image, and its 
boundary rectangle. 

boundary rectangle: A rectangle defined as part of a bitmap, which encloses 
the acUve area of the bit image and imposes a coordinate system on it Its 
top left comer is always aligned around the fint bit in the bit image. 

cameia eye: A concept in three-dimensional graphics: the point of view aid 
the viewing angle in which an object ^apears, irKtepenctent of the obit's 
coordinates. 

chaiacteT style: A set of stylistic variations^ such as bold, italic, and 
underline. The empty set indicates normal text (no stylistic variations). 

clipping: Limiting drawing to within the bounds of a particular area 

clipping regian: Same as clipRgn. 

clipRgt The region to which an application limits drawing in a grafPort 

coonfinate plane: A two-dimensional grid. In QuickDraw, the grid coordinates 
are integers ranging from -32768 to ♦SZye?, and all grid lines are infinitely 
thia 

cursor A 16-by- 16-bit image that ap|:»an on the screen aid is controlled by 
the mouse. 

cursor level: A value, initialized to when the system is booted, that keeps 
track of the number of times the cursor has been hiddea 

empty: Containing no bits, as a sh^ie defined by only one point 

font The complete set of characten of one typeface, such as Century. 

frame: To draw a shape by drawing an outline of it 

global coonfinate system: The coordinate system based on the top left comer 
of the bit image being at (0,0), 

GrafBD: A three-dimensional graphics unit that calls QuickDraw routines. 

grafPort- A complete drawing environment, including such elements as a 
bitmap, a subset of it in which to draw, a character font, patterns for drawing 
and erasing, and other pen characteristics. 

grafPtn A pointer to a grafPort 

handle: A pointer to one master pointer to a dynamic, relocatable data 
structure (such as a region). 

hotspot The p»int in a cursor that is aligned with the mouse position. 

kem: To stretch part of a character back under the previous character. 
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local coorcfinate system: The coordinate system local to a grafPort, imposed 
by the boundary rectangle defined in its bitmap. 

missing symbol* A character to be drawn in case of a request to draw a 
character that is missing from a particular font 

pattern: An 8-by-8-bit image^ used to define a repeating design (such as 
stripes) or tone (such as gra^ 

pattern transfer mode: One of eight transfer modes for drawing lines or 
shapes with a pattern. 

picture: A saved sequence of QuickDraw drawing commands (and, optionally, 
picture comments) that you can play back later with a single procedure call; 
also, the image resulting from these commands. 

picture comments: Data stored in the definition of a picture which does not 
affect the picture's appearance but may be used to provide additicnal 
information about the picture when it's played back. 

picture ftame: A rectangle, defined as part of a picture, which surrounds the 
picture and gives a frame of reference for scaling when the picture is drawa 

pixel: The visual representation of a bit on the screen (white if the bit is 0, 
black if it's \\ 

point: The intersection of a horizontal grid line and a vertical grid line on 
the coordinate plane, defined by a horizontal and a vertical coordinate. 

polygon: A sequence of connected lines, defined by QuickDraw line-drawing 
commands. 

port QrafPort or Port3D. 

Port3D: A data structure in GrafSD that maps three-dimensional coordinates 
into a two-dimensional QuickDraw grafPort 

Port3DPtK A pointer to a Port3D. 

portBits: The bitmap of a grafPort 

portBitsJx)unds: The boundary rectangle of a grafPort's bitmap. 

portRect A rectangle, defined as part of a grafPort, which encloses a sutiset 
of the bitmap for use by the grafPort 

re0on: An arbitrary area or set of areas on the coordinate plane. The 
outline of a region should be one or more closed loops. 

row width: The number of bytes in each row of a bit image. 

scale: To shrink or expand by a specified factor. 

solid: Filled in with any pattern 

source transfer mode: One of eight transfer modes for drawing text or 
transferring any bit image between two bitmaps. 
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style: See character style. 

thePort: A global variable that points to the current grafPort 

thePort3D: A global variable that points to the current Port3D. 

transfer mode: A specification of which boolean operation QuickDraw should 
perform when drawing or when transferring a bit image from one bitm^ to 
another. 

translate: To move in three-dimensional space by a specified amount 

transfoimation matrix: Same as xForm matrix 

viewing pyianM The portion of three-dimensional ^)ace that a camera eye 
can see. The pyramid's apex is the point of the camera eye; its base is the 
viewRect in a Port3D. 

visRgn: The region of a grafPort which is actually visible on the screen. 

xFoim matrix A 4x4 matrix that holds an equation to transform points 
plotted in three-dimensional coordinates into two-dimensional screen 
coordinates. 
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FA "me Mouse - F-1 

F,l.l Mouse Location F-1 

F.1.2 Mouse Update Frequency F-1 

F.1.3 MouseScaling F-1 

F.l.a Mouse Odometer F-2 

F^ TheCunor F-2 

F,2.1 Cursor/Mouse Tracking F-3 

F.2.2 TheBusy Cursor F-3 

F J The Display Screen F-4 

F.3.1 Screen Contrast F-a 

F.3^ Automatic Screen Fading F-4 

F.4 TUB Speaker F-5 

F.5 The Keyboard F-5 

F5.1 Keyboard Identification F-7 

F.5.2 Keyboard State F-8 

F.5.3 Keyboard Events F-8 

F.5.4 Dead Key Diacriticals F-IO 

F.5.5 Repeats F-11 

Fj6 ITie h^dosecond Timer F-11 

F.7 TTiB MUUsecond Timer F-12 

F^ DateandTlme F-12 

F.9 TimeStamp F-12 

F.10 Interface of the Hardware Uiit F-13 



Hardware Interface 



The hardware Interface software provides an interface for accessing and 
controlling several parts of the Lisa hardware. The hardware/software 
capabilities addressed include the mouse, the cursor^ the display, the contrast 
control, the speaker, tjoth undecoded and decoded keytxjard access, the micro- 
second and millisecond timers and the hardware clock/calendar. 

This appendix contains Pascal procedure and function declarations interleaved 
with text describing them. Pascal type declarations and a summary of the 
function and procedure declarations can be found in Section F.IO, Interface of 
the Hardware Unit 

Programs using this unit should be compiled against the file QD/Hardware.CBJ 
and linked to the file C)D/HWIntL.C)BJ. 

F.1 THe Mouse 
F.1.1 Mouse Location 

Procedure MouscLocation (var x Pixels; var y. Pixels); 

The mouse is a pointing device used to indicate screen locations. 
MouseLocation returns the location of the mouse. The X-coordinate can range 
from to 719, and me Y-coordinate from to 363. The initial mouse 
location is DA 

F.1J2 Mouse Update Frequency 

Procedure MouseUpdates (delay: MUUSeconds); 

Software knowledge of the mouse location is updated periodically, rather than 
continuously. The frequency of these iptetes can be set by calling 
MouseUpdates. The time between updates can range from milliseconds 
(continuous updating) to 28 milliseconds, in intervals of 4 milliseconds. The 
initial setting is 16 milliseconds. 

F.1.3 Mouse Scaling 

Procedure MouseScaling (scaled9oolean); 

Procedure MouseTTiresh (threshold: Pixels); 

The relationship between physical mouse movements and logical mouse move- 
ments is not necessarily a fixed linear mapping. Three alternatives are 
available: 1) unsealed, 2) scaled for fine movement and 3) scaled for coarse 
movement Initially mouse movements are unsealed. 

When mouse movement is unsealed, a horizontal mouse movement of x units 
yields a change in the mouse X-coordinate of x pixels. Similiarly, a vertical 
movement of y units yields a change is the mouse Y-coordinate of y pixels. 
These rules apply independent of the speed of the mouse movement 
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When mouse movement is scaled, horizontal movements are magnified by 3/2 
relative to vertical movements. This is to compensate for the 2/3 aspect 
ratio of pixels on the screen. When scaling is in effect, a distinction is made 
between fine (small) movements and coarse (large) movements. Fine move- 
ments are slightly reduced, while coarse movements are magnified. For scaled 
fine movements, a horizontal mouse movement of x units yields a change in 
the X-coordinate of x pixels, but a vertical movement of y units yields a 
change of (2/3)^y pixels. For scaled coarse movements, a horizontal movement 
a X units yields a change of (3/2)*x pixels, while a vertical movements of y 
units yields a change of y pixels. 

The distinction between fine movements and coarse movements is determined 
by the sum of the x and y movements each time the mouse ICK^ation is 
updated. If this sum is at or below the t/ve^iol(i the movemait is considered 
to be a fine movement Values of the threshold range from (which yields all 
coarse movements) to 256 (which yields all fine movements). Given the 
default mouse updating frequency, a threshold of about 8 (threshold's initial 
setting) gives a comfortable transition between fine and coarse movements. 

MouseScallng enables and disables mouse scaling. MouseThresh sets the 
threshold between fine and coarse movements. 

F.1.4 Mouse Odometer 

Function MouseCdometen ManyPixels; 

In order to properly specify, design and test mice, it's Important to estimate 
how far a mouse moves during its lifetime. MouseOdameter returns the sum 
of the X and Y movements of the mouse since boot time. The value returned 
is in (unsealed) pixels. There are 180 pixels per inch of mouse movement 

F.2 The Cursor 

Procedure Cursorbnage (hotX: Pixels; hotY: Pixels; height: CursmHeight; data: 
CiffSorPtr; mask: CXirsoiPtr); 

The cursor Is a small image that is displayed on the screea Its shape is 
speciHed by two bitmaps, called data and mask. ITiese bitmaps are 16 bits 
wide and from to 32 bits high. The rule used to combine the bits already 
on the screen with the data and mask Is 

screen <- (screen and (not mask]^ xnr data. 

The effect is that white areas of the screen are replaced with the cursor 
data. Black areas of the screen are replaced with (not mask) xor data If the 
data and mask bitmaps are identical, the effect is to or the data onto the 
screws 

The cursor has both a location and a hotspot The location is a position on 
the screen, with X-coordinates of to 719 and Y-coordinates of to 363, 
The hotspot is a position within the cursor bitmaps, with X- and Y-coordi- 
nates ranging from to 16. The cursor is displayed on the screen with its 
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hotspol at its location. If me cursor's location is near an edge of trie screen, 
the cunor image may be partially or completely off the screea 

Most cursor operations can be performed by calling the SetCursor, httdeCursor, 
ShowCXflTsor, and GbscureCXirsor procecftjres defined by QuickDraw (see Section 
E.9.2, Cursor-Handling Routines). Additional capabilities are provided by the 
Hardware Interface routines described below. 

The Cursorlmage procedure is used to specify the data bitmap, mask bitmap, 
height and hot^xjt of the cursor. Initially the cursor data and mask bitmaps 
contain all zeros, which yields a blank (invisible) cursor. The initial hotspot is 
0,0. 

F.Z1 Cursor/Mouse Tracking 

PiDcedure CunorTracking (track: Boolean); 

Prt3cedure CursoiLocation (x: Pixels; y: Pixels); 

CursorTracklng enables and disables cunor tracking of the nxxise. When 
tracking is envied, the cursor location is changed to the mouse location each 
time the mouse moves. Setting the cunor location by calling CXusorLcx^ation 
will have no effect; the cursor sticks with the mouse. 

When tracking is disabled, Mne rnouse location end cursor location are inctepen- 
dent Calling CursorLocatlon will move the cunor; moving the mouse will not 

When tracking is fint enabled (i.e., on each transition from disabled to 
enabled) the mouse location is modified to equal the cunor location. There- 
fore, ena4)ling tracking does not move the cunor; it does modify the mouse 
location. Initially tracking is enabled. 

F.2.2 T?ie Busy Cursor 

Procedure Busylmage (hotX: Pixels; hotY: Pixels; height: CursoiHeight; data 
CursorPtr; mask: CursoiPtr); 

Procedure BusyOelay (del^ Milliseconds); 

Applications may desire to display a txjsy cursor (e.g., an hourglass) when an 
operation in progress requires more than a few seconds to complete. The 
Busylmage procedure is used to specify the data bitmap, mask bitmap, height 
and hot^t of the busy cursor. 

A call to BusyOelay specifies that the normal cursor should currently be 
displayed, and that display of the twsy cursor strauld be ctelayed for the 
specified nurrtier of milliseconds. Sttosequent calls to BusyOelay override 
previous calls, postponing display of the busy cursor. If no calls to BusyOelay 
occur for the specified nurrtjer of millisecorxls, the busy cursor will be 
displayed until the next call to BusyOelay. 

Initially the busy cunor data and mask bitmaps contain all zeros, which yields 
a blank (invisible) cursor. The initial hotspot is OA The initial busy delay is 
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infinite, that is, the txjsy cursor will not be displayed until BusyOelay is 
called 

F3 The Display Screen 

Procedure ScreenSize (var xr Pixels; var y: Pixels); 

The display screen is a bit mapped display; that is, each pixel on the screen 
is controlled by a bit in main memory. The display has 720 pixels horizontally 
and 364 lines vertically, and therefore requires 32,760 bytes of main memory. 
The screen size may be determined by calling ScreenSize. 

Function FrameCXiunten Frames; 

The screen is redisplayed about 60 tinnes per second. A franm cajnter is 
incremented between screen updates, at the vertical retrace interrupt The 
frame cointer is an unsigned 32-bit integer which is reset to each time the 
machine is booted. FrameOounter returns this value. An application can 
synchronize with the vertical retraces by watching for charges in the value of 
this counter. The frame counter should not be used as a timer; use the 
millisecond and mircosecond timers instead. 

F3.1 Screen Contrast 

Function Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 

The display's contrast level is under program control. Contrast values range 
from to 255 ($FF), with as maximum contrast arid 255 as minimum. 
Contrast returns the contrast setting; SetContrast sets the screen contrast 
Tte low order two bits of the contrast value are ignored. The initial contrast 
value is 128 ($80> 

Procedure RampContrast (contrast ScreenContrast); 

A sudden chaige in the contrast level c^ be jarring to the user. 
F^mpContrast gradually changes the contrast to the new setting over a period 
of about a second. RampContrast returns immediately,, then ramps the 
contrast using interrupt driven processing. 

F.31.2 Automatic Screen Fading 

Function DimContrast: ScieenContiast; 

Procedure SetDimContrast (contrast ScreenContrast); 

The screen contrast level is automatically dimmed if no user activity is noted 
over a specified period (usually several minutes). This is done in order to 
preserve the screen phospher. C^mContrast returns the contrast value to which 
the screen is dimmed; SetOimCcntrast sets this value. The initial dim 
contrast setting is 176 ($80> 
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Function FadeOelay: ^filliSeconds; 

Procedure SetFacJeOelay (delay: ^ttUlSefxmds); 

The delay between the last user activity and dimming of the screen is under 
software control. FadeOelay returns the fade delay; SetFadeDelay sets it 
The actual delay will range from the specified delay to twice the specified 
delay. The initial delay period is five minutes. 

When the screen is dim, user interaction will cause the screen contrast to 
return to its normal bright level (determined by the Contrast and SetContrast 
routines defined abovejt Moving the mouse or pressing a key on the keyboard 
(e.g., SHIFT) is enough to trigger the screen brightening. Calling 
CursoiLocation or SetFadeDelay also indicates user activity. 

F.4 The Speaker 

Function Volume: SpeakeiVolume; 

Pnx^dure SetVblume (volume: SpeakeiVoIume); 

Procedure Noise (waveLength: Microseconds); 

Procedure 91ence; 

Procedure Beep (waveLength: Microseconds; duration: Milliseconds); 

The routines in this section provide square wave output from the Lisa speaker. 
The speaker volume can be set to values in the range (soft) to 7 (loud)L 
Volume reads the volume setting; SetVolume sets it The initial volume 
setting is 4. 

Noise produces a square wave of approximately the specified wavelength. 
Silence shuts off the square wave. The minimum wavelength is about 8 
microseconds^ which corresponds to a frequency of 125^00 cycles per second, 
well ^xjve the audible range. The maximum wavelength is 8,191 micro- 
seconds, which corre^3onds to about 122 cycles per second. 

Noise and Silence are called in pairs to start and stop square wave output In 
contrast. Beep starts square wave output which will automatically stop after 
the specified period of time. The effects of Noise, Silence and Beep are 
overridden by subsequent calls. 

F.5 T?ie Keyboard 

The routines in this section provide an interface to the keytxiard, the keypad, 
tf^ mouse txjtton and plug, the diskette buttons and insertion switches, and 
the power switch. Two interfaces are provicted, a poUable keyboard state and 
a queue of keyboard events. 

Three physical keyboard layouts are defined, the "Old US Layout" (with 73 
keys on the main keyboard and numeric keypad), the Tinal US Layout" (76 
keys) and the "European Layout" (77 keys). Each key has been assigned a 
keycodei which uniquely identifies the key. Keycode values range from to 
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127. Table F-i defines the keycodes for the "Final US Layout", using the 
legends from the US Keyboard. The "Old US Layout" has three less keys; |V 
Alpha Enter, and Right Option are not on the old keyboard. The "European 
Layout" has one additional key, ><, with a keycode of $43. 

Tv»«) keys on the "CHd US Layout" generate keycodes different from the 
corresponding keys on the "Final LS Layout". To aid in compatibility, 
software changes the keycode for ~ ' from $7C lo $68, and the keyaxJe for 
Right QpUon from $68 to $06. 

Table F-i 
Keycodes for Tinai US Layout" 



HIGH-* 
LOU 


000 



001 
1 


010 
2 


Oil 
3 


100 
4 


101 
5 


110 
6 


111 
7 


QOOQ 








CLEAR 




— 


( 
9 


E 


A 


0001 

1 


DISK 1 
INSERTED 




- 




* 


) 



6 


2 


QOIQ 
2 


DISK 1 
BUTTON 




i^ 




1 

\ 


U 


& 

7 


# 
3 


0011 
3 


DISK 2 
INSERTED 










I 


8 


$ 
4 


0100 
4 


DISK 2 
BUTTON 




7 




P 


J 


% 
5 


1 
1 


0101 
5 


PARALLEL 
PORT 




8 




BACKSPACE 


K 


R 


Q 


0110 
6 


HOUSE 
BUTTON 




9 




ALPHA 
ENTER 


< 
[ 


T 


S 


Dill 

7 


HOUSE 
PLUG 




rii 


f 




} 
3 


Y 


W 


1000 
8 


POUER 
BUTTON 


: 


4 




RETU»( 


M 


~ 


TAB 


1001 
9 






5 







L 


F 


z 


1010 

A 






6 






f 


G 


X 


1011 
B 






LfJ 




: 


* 


H 


D 


1100 
C 




\ 


• 


: 


? 

/ 


SPACE 


V 


LEFT 
OPTION 


1101 
D 




: 


2 


: 


1 


< 

* 


C 


CAPS 
LOCK 


1110 
E 




: 


3 


: 


RIGHT 
OPTION 


> 


B 


SHIFT 


1111 

F 






MlfERIC 
ENTER 


: 







N 


« 
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F5.1 Keyboard idenUflcaUon 

Function Keytjoard: Keytxfld; 

Function Legends: Keytxfld; 

Procedure SetLegends Qd: Keytxfld); 

Llsa software supports a host of different keyboards. Each keyboard has three 
major attributes: manufacturer^ physical layout, and legends. The chart 
below describes how these three attributes are combined to form a keyboard 
identl- flcatlon number. The keyboards self Identify when the machine Is 
turned on and when a new keyboard is attached. Keyboaflrd returns the 
Identification number of the keyboard currently attached. Legends and 
SetLegends provide a means of pretending to have different legends, without 
physically replacing the keyboard. 

Keyboard Identification numbers: 

7 65 4 3 2 1 

I Manufacturer \ Layout I Legends I 



Manufacturer: 


00 ~ 


APD (l.e., TKC) 


01 - 




10 -- 

1 aum it> 


Keytronics 


i-ayuut. 

00 ~ 


Old US (73 keys) 


01 — 




10 ~ 


European (77 keys) 


11 — 


Final US (76 keys) 


LayoutA_egenrts: 


$0F ~ 


Old US 


$26 - 


Swiss-German 


$27 ~ 


Swiss-French 


$29 ~ 


Portuguese 


$29 ~ 


Spanish-Latin American 


$2A ~ 


Danish 


$2B ~ 


Swedish 


$2C ~ 


Italian 


$2D ~ 


French 


$2E ~ 


German 


$2F ~ 


UK 



(allocated for proposed software) 
(allocated for proposed software) 
(allocated for prqDosed software} 
(allocated for proposed software) 
(allocated for proposed software) 
(hardware not yet available) 
(hardware not yet available) 
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$3C ~ APL (allocated for proposed software) 

$3D ~ French-Canadian (allocated for proposed software) 

$3E ~ US-Dvorak (allocated for proposed software) 

$3F ~ Final us 

?32. Keytjoard State 

Function KeylsOown (key: Keycap> Boolearu 

Proceduie KeyMap (var keys: KeyCapSet); 

Low level access to the keyboard Is provided through a poUable keyboard 
state. This state Information Is based on the physical keycodes defined above. 
KeylsOown returns the position of a single specified key. KeyMap returns a 
128-bit map, one bit for each key. A zero Indicates the key is up, a one 
Indicates down. For the mouse plug, a zero Indicates unplugged, a one indi- 
cates plugged In. Certain keys are not pollable; the corresponding bits will 
always be zero. These keys are the diskette Insertion switches and buttons, 
parallel port, and power switch. (The parallel port and mouse plug keys are 
unreliable across reboots on older hardware.) 

F.5.3 Keyboard Events 

The hardware Interface provides a queue of keyboard events. The events In 
the Input queue are generally key down transitions. Each event contains the 
following Information: 

keycode ~ physical key 

ascli ~ ASCII interpretation of this key 

state ~ caps-lock, shift, option, C mouse button and repeat 

mousex ~ x-coordlnate of the mouse when the key was pressed 

mouseY ~ Y-coordlnate of the mouse when the key was pressed 

time ~ value of the millisecond timer when the key was pressed 

Keycode ~ Keycodes are defined in Table F-l, above. 

Ascli ~ The ASCII interpretation of keys depends on the state of the caps- 
lock, shift and option keys. Six interpretations are associated with each 
different keyboard layout: 

normal 

caps-lock 

shift or both shift and caps-lock 

option 

option with caps-lock 

option with shift or both shift and caps-lock 
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In nxjsl cases Wie ASCII value returned Is obvious. The table below lists the 
cases that aren't so obvious. 

Disk \ Inserted 

Disk 1 Button 

Disk 2 Inserted 

Disk 1 Button 

Power Button 

Mouse Button (down) 

Mouse Plug (in) 

Mouse Button (up) 

Mouse Plug (out) 

Enter 

Backspace 

Tab 

Return 

Clear 

$1C (FS) Left 

$1D (GS) Right 

$1E ps) Up 

$1F aJS) Down 

$20 (SP) Space 

State — A 16-bit word is used to return the state of several keys with each 
event Each bit represents one or more keys; a zero indicates that all of the 
keys are up, a one indicates that at least one of the keys is dowa An 
additional bit indicates, if it is a one, that the event was generated by 
repeating the previous event The following bits of state are currently 
assigned: 




bit 0: 


caps-lock 


bit 1: 


left or right shift 


bit 2: 


left or right option 


bit 3: 


« key 


bit 4: 


mouse button 


bit 5: 


this event is a repeat 



Certain keys never generate events. These keys are caps-lock, both shift 
keys, option keys, and the < key. The mouse button generates events on both 
the down and up transitions. Down transitions have an ascii value of 0, up 
transitions 1. The mouse plug also generates two different events. When the 
mouse is plugged in an event with an ascli value of is returned, when it is 
unplugged a value of 1 is returned. 
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Function KeytxPeek (repeats: Booleaa* index^ KeytxJQindex; var event: 
KeyEvent> Booleea* 

KeytJcPeek is used to examine events in the keytioard queue, without removing 
them from the queue. The first input parameter indicates whether .repeats are 
desired. The second parameter Is the queue index. The first output para- 
meter indicates whether the specified queue entry contains an event To 
examine an entire queue, fint call KeylJdPeek with a queue index of 1. If an 
event is returned, call it again with a queue index of 2, etc. 

Function KeytxEvent (repeats: Boolean; wait: Boolean; var event KeyEvent> 
BoDleon; 

KeybdEvent is used both to determine if a keytaoard event is available, and to 
return the event if one is available. The event is removed from the queue. 
KeybdEvent returns a boolean result which is true if an event is returned. 
The first parameter to KeybdEvent is used to indicate if the caller will 
accept repeated events on this call. The second parameter indicates if the 
functions should wait for an event if one is not immediately availabla 

F3.4 Dead Key Oiacriticals 

Many languages employ diacritical marks on certain letters. Several of the 
required diacritical mark-letter combinations appear on European keyboards, 
but others do not. The combinations shown in the table below may be typed as 
a two-key sequence, by first typing the dead key diacritical (which has no 
immediate effect^ and then typing the letter. Dead key diacriticals appear on 
keytx)ard legends as the diacritical mark over a dotted square or hollow box 



circumflex * — a 


A A A A 

e 1 u 


grave accent * ~ a 


e i 6 a 


tilde T "" 3 


fifsl 


acute accent ~ a 


e^ i 6 Q 


umlaut " ~ aA 


e T oOuO 



A dead key diacritical followed by a letter which appears in the table above 
yields the corresponding character. The event that is generated contains the 
keycode, state, mouse location and time that correspond to the letter, but the 
ASCII value of the letter-diacritical combination. A dead key diacritical 
followed by a space yields just the diacritical mark. The event contains the 
keycode, state, mouse location and time corresponding to the space, but the 
ASCII value of the diacritical mark. Finally, a dead key diacritical followed 
by any other character (i.e., not a space or defined letter) yields the diacrit- 
ical mark followed by the other character. 

diacritical, defined letter ~> foreign character 

diacritical, space ~> diacritical 

diacritical, other character ~> diacritical, other character 
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F35 Repeats 

Most keys, if held down for an extended period of time, may generate 
multiple events (repeats). The keys that are not repeat^le are c^s-lock, 
both shifts, both options, the # key, the diskette insertion switches and 
diskette buttons, parallel poit, the mouse button and plug, and the power 
button. Several conditions must be satisfied before a repeat is generated. 
These conditions are as follows: 

1. KeybdPeek or KeytxJEvent is called with repeatsOesiied true. 

2. The keyboard event queue is empty. 

3. The key returned in the last event is still down. 

4. No down transitions have occurred since the last event 

5. The key is repeatable. 

6. Enough time has elapsed. 

Repeats generate events with the following attributes: 

keycode ~ original keycode 

ascii ~ original ASCII interpretaticwi 

state ~ original position of the caps-lock, shift, etc. 

mouseX ~ revised X-coordinate of the mouse 

mouseY ~ revised Y-coordinate of the mouse 

time — revised value of the millisecond timer 

Procedure RepeatRate (var initial: MilliSeconcts; var subsequent: Milliseconds); 

Procedure SetRepeatRate (initial: Milliseconds; subsequent- ^ttlliSeconds); 

The repeat rates can be read and set by calls to RepeatRate and 
SetRepeatRate. The rates include an initial delay, which c«curs prior to the 
fint repetition, and a subsequent delay, prior to additional repetitions. They 
are both in units of milliseconds. The default repeat rates are 400 
milliseconds initially and 100 milliseconds subsequently. 

F.6 The Microsecond Timer 

Function MicroTimen r^croseconds; 

The ^ttcroTimer function simulates a continuously running 32-bit counter 
which is incremented every microsecond. The timer is reset to each time 
the machine is booted. The timer changes sign about once every 35 minutes, 
and rolls over about every 70 minutes. 

The microsecond timer is designed for performance measurements. It hee a 
resolution of 2 microseconds. Calling MicroTlmer from Pascal takes about 135 
microseconds. Note that interrupt processing will have a major effect on 
microsecond timings. 
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F.7 T?ie h4imsecond Timer 

Function Timen Milliseconds; 

The Timer function simulates a continuously amning 32-bit counter which is 
incremented every millisecond. The timer is reset to each time the 
machine is booted. The timer changes sign about once every 25 days, and 
rolls over about every 7 weeks. 

The millisecond timer is designed for timing user interactions such as mouse 
clicks and repeat keys. It can also be used for performance measurements, 
assuming that millisecond resolution Is sufficient 

F.8 Date and Time 

PiDcedure OateTime (var date: DateAnay); 

Procedure SetOateTime (date: OateAnray); 

Procedure DateToTime (date: OateArray; var time: Seconds); 

The current date and time are available as a set of 16-bit integers which 
represent the year, day, hour, minute and second, by calling OateTime and 
SetOateTime. The date and time are based on the hardware clock/calendar. 
This restricts dates to the years 1980-1995. The clock/calendar continues to 
operate during soft power off^ and for brief periods on battery backup if the 
machine is unplugged. If the clock/calendar hasn't been set since the last loss 
of battery power, the date and time will be midnight prior to January 1, 1980. 
Setting the date and time also sets the time stamp described below. 
OateToTime converts a date and time to a time stamp, defined In the next 
sectioa 

F.9 Time Stamp 

Function TlmeStamp: Seconds; 

Procedure SetTlmeStamp (time: Seconds); 

Procedure TimeToOate (time: Seconds; var date: l^ateArray); 

The current date and time are also available as a 32-blt unsigned Integer 
which represents the number of seconds since the midnight prior to 1 January 
1901, by calling TimeStamp and SetTlmeStampi The time stamp will roll over 
once every 135 years. Beware—for dates beyond the mid 1960*s, the sign bit 
Is set The time stamp Is based on the hardware clock/calendar. This cl(x^ 
continues to operate during soft power off, and for brief periods on battery 
backup if the machine Is unplugged. If the clock/calendar hasn't been set 
since the last loss of battery power, the date and time will be midnight prior 
to January 1, 1980. Setting the time stamp also sets the date and time 
described above. Since the date and time is restricted to 1980-1995, the time 
stamp Is also restricted to this range. TimeToOate converts a time stamp to 
the date and time format defined above. 
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F.IO Interface of the Hardware Uhit 

Unit Hardirare; 
Interface 



type 



Pixels 

ManyPixels 

CursorHeight 

CursorPtr 

OateArray 



Frames 

Seconds 

Milliseconds 

Microseconds 

SpeakerVolume 

ScreenContrast 

KeytxjQIndex 

Keybdid 

Keycap 

KeyCapSet 

KeyEvent 



{ Mouse } 



= Integer; 
= Longint; 
= Integer; 
= "Integer; 
= Record 

year: Integer; 

day: Integer; 

hour: Integer; 

minute: Integer; 

second: Integer; 

end; 

- Longint; 
= Longint; 
= Longint; 
= Longint; 

- Integer; 
= Integer; 
= I.-IOOO; 
= Integer; 

= 0..127; 

= Set of Keycap; 

= Packed Record 

key: Keycap; 

ascii: Char; 

state: Integer; 

nouseX: Pixels; 

mouseY: Pixels; 

time: Milliseconds; 

end; 



Procedure MouseLocation (var x: Pixels; var y: Pixels); 
Procedure Mouselipdates (delay: MilliSecwids); 
Procedure MouseScaling (scale: Boolean); 
Procedure MouseThresh (threshold: Pixels); 
Function MouseOdometer: ManyPixels; 
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{ Cura.)! } 

Prasedure CursorLcKation (x: Pixels; y: Pixels); 
Pro;)eclure CursorTracking (track: Boolean); 
ProtDedure Cursorlmage (hotX: Pixels; hotY: Pixels; height; 
<XirsorHeight; data: CursorPtr; mask: CursorPtr); 

Procjedure Busy Image (hotX: Pixels; hotY: Pixels; height: 

(XirsorHeight; data: CursorPtr; mask: CursorPtr); 
Procedure BusyOelay (delay: HilliSeconds); 



{ Scre<^ } 

FuncJtion FrameCounter : Frames; 

Procedure ScreenSize (var x: Pixels; var y: Pixels); 

Function Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 

Procedure RanpContrast (contrast: ScreenContrast); 

Function DimContrast: ScreenContrast; 

Procedure SetOimContrast (contrast: ^ireenContrast); 

Function FadeOelay: Milliseconds; 
Profredure SetFadeDelay (delay: Milliseconds); 



{ SpeaJcer } 

FuncJtion Volume: ^peakerVolume; 

Pro(jedure SetVolume (volume: SpeakerVolume); 

Procedure Noise (wavelength: Microseconds); 

Pra:«dure Silence; 

Procedure Beep (wavelength: Microseconds; duration: Milliseconds); 
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{ Keyboard > 

Function KeylDoard: Keybdid; 

Function Legends: Keybdid; 

Procedure SetLegends (id: Keybdid); 

Function KeylsOown (key: KeyCap): Boolean; 

Procedure Keyttep (var keys: KeyCapSet); 

Function KeybdPeek (repeats: Boolean; index: KeybdQIndex; var 

event: KeyEvent): Boolean; 
Function KeybdEvent (repeats: Boolean; wait: Boolean; var event: 

KeyEvent): Boolean; 
Procedure RepeatRate (var initial: Milliseconds; var subsequent: 

Milliseconds); 
Procecftjre SetRepeatRate (initial: Milliseconds; subsequent: 

Milliseconds); 



{ Timers } 

Function MicroTimer: Microseconds; 
Function Timer: Milliseconds; 



{ Date and Time } 

Procedure DateTime (var date: OateArray); 

Procedure SetDateTime (date: OateArray); 

Procedure DateToTime (date: OateArray; var time: Seconds); 



{ Time Stamp } 

Function TimeStamp: Seconds; 

Procedure SetTimeStamp (time: Seconds); 

Procedure TimeToOate (time: Seconds; var date: OateArray); 
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1 


2 


3 


4 


5 


6 


7 


8 


9 


A 


B 


C 


D 


E 


F 





NUL 


OLE 


SP 





@ 


P 


\ 


P 


: 




• 






: 






1 


SON 


DCl 


1 

• 


1 


A 


Q 


a 


q 






; 






i 






2 


STX 


DC2 


»» 


2 


B 


R 


b 


r 


• 




: 






: 






3 


ETX 
Enter 


DC3 


# 


3 


C 


S 


c 


s 






: 






: 






a 


EOT 


0C4 


$ 


4 


D 


T 


d 


t 


• 




: 






; 






5 


ENO 


NAK 


% 


5 


E 


U 


e 


u 






. 






; 






6 


ACK 


SYN 


& 


6 


F 


V 


f 


V 






• 












7 


BEL 


ETB 


t 


7 


G 


w 


g 


w 






; 












8 


BS 


CAN 


( 


8 


H 


X 


h 


X 






• 






i 






9 


HT 


en 


) 


9 


I 


Y 


i 


y 






: 












A 


LF 


SUB 


n 


• 
« 


J 


Z 


J 


z 






: 






; 






B 


VT 


ESC 
Clou 


+ 


• 


K 


[ 


k 


{ 






. 












C 


FF 


FS 

•i4\ 


» 


< 


L 


\ 


1 








: 






': 






D 


CR 


GS 


- 


= 


M 


] 


m 


} 






: 






': 






E 


SO 


fin 


* 


> 


N 


A 


n 


~ 






: 






': 






F 


SI 


i^ 


/ 


7 

• 










DEL 






i 






': 







The first 32 characters and DEL are norprinting control cocies. 
The Shaded area is reserved for future use. 
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Appendix H 
Error Messages 



Kl Lexical Enon H-1 

K2 SyntacUc Enon H-1 

K3 Semantic Emm H-2 

Kft Conditianal CompUaUon H-4 

K5 Oompiler Specific Limitatiaris H-4 

K6 I/O EnoK H-4 

K7 Clascal Emon H-4 

K8 Code Generation Enors H-5 

K9 Nfterification Enors H-5 



Appendix H 
Error Messages 



Kl 



K2 



Lexical Eiron 

10 Too many digits 

11 Digit expected after ' . * in real 

12 Integer overflow 

13 Digit expected in exponent 

14 End of line encountered in string constant 

15 Illegal character in infxit 

16 Premature end of file in source program 

17 Extra characters encountered after end of program 

18 End of file encountered in a comment 



Syntactic Enors 
20 Illegal symbol 

Error in simple type 
Error in declaration part 
Error in parameter list 
Error in constant 
Error in type 
Error in field list 
Error in factor 
Error in variable 
Identifier expected 
Integer expected 



21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 



(• expected 

)• exjDected 

[• exjjected 

]* expected 

:' expected 

;* ex|3ected 

«* expected 

, * expected 

*• expected 

:=• expected 

program' expected 

of* expected 

begin' expected 

end' expected 

then' expected 

until' expected 

do' expected 

to' or 'do«nto* expected 
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49 'file' expected 

50 'if* expected 

51 • . ' expected 

52 'implementation' expected 

53 'interface' expected 

54 'intrinsic' expected 

55 'shared* expected 

HL3 Semantic Enors 

100 Identifier declared twice 

101 Identifier not of the appropriate class 

102 Identifier not declared 

103 Sign not allowed 

104 Number expected 

105 Lower bound exceeds upper bound 

106 Incompatible subrange types 

107 Type of constant must be integer 

108 Type must not be real 

109 Tagf ield must be scalar or subrange 

110 Type incompatible with with tagfield type 

111 Index type must not be real 

112 Index type must be scalar or subrange 

113 Index tyJDe must not be integer or longint 

114 Unsatisfied forward reference 

115 Forward reference type identifier cannot appear in vari^le 

declaration 

116 Forward declaration - repetition of parameter list not allowed 

117 Forward declared function - repetition of result type not allowed 

118 Function result type must be scalar, subrange, or pointer 

119 File value parameter not allowed 

120 Missing result type in function declaration 

121 F -format for real only 

122 Error in type of standard function parameter 

123 Error in type of standard procedure parameter 

124 Number of f^rameters does not sgree with declaration 

125 Illegal parameter substitution 

126 Result type of parameteric function does not agree with 

declaration 

127 Expression is not of set type 

128 Only tests on equality allowed 

129 Strict inclusion not allowed 

130 File comparison not allowed 

131 Illegal type of operand(s) 

132 Type of operand must be boolean 

133 Set element type must be scalar or subrange 

134 Set element t)^s mt compatible 

135 Type of variable is not array or string 

136 Index type is not compatible with declaration 
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137 Type of variable is vol record 

138 TyJDe of variable must be file or pointer 

139 Illegal type of loop control variable 

140 Illegal type of expression 

141 Assignment of files not alloved 

142 Label type incompatible with selecting expression 

143 Subrange bounds must be scalar 

144 Type conflict of operands 

145 Assignment to standard function is not allowed 

146 Assignment to formal function is not allowed 

147 No such field in this record 

148 Type error in read 

149 Actual parameter must be a variable 

150 hultidefined case label 

151 Missing corresponding variant declaration 

152 Real or string tagfields not alloifed 

153 Previous declaration «*as not forward 

154 Substitution of standard procedure or function is not allowed 

155 Multidefined label 

156 Hultideclared label 

157 Undefined label 

158 Undeclared label 

159 Value parameter expected 

160 Multidefined record variant 

161 File not allowed here 

162 Unknown compiler directive (not 'external* or 'forward') 

163 Variable cannot be packed field 

164 Set of real is not allowed 

165 Fields of packed records cannot be var parameters 

166 Case selector expression must be scalar or subrange 

167 String sizes must be equal 

168 String too long 

169 Value out of range 

170 Address of standard procedure cannot be taken 

171 Assignment to function result must be done inside function 

172 Loop control variable must be local 

173 Label value must be in 0..9999 

174 Must exit to an enclosing procedure 

175 Procedure or function has already been declared once 

176 Missing procedure or fiiiction body 
190 No such unit in this file 
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HA Concfitianal ConipUaUan 

260 New compile- time variable must be declared at global level 

261 Undefined carpi le-tlme variable 

262 Error in compile- time expression 

263 Conditional compilation options nested too deeply 

264 Unmatched ELSEC 

265 Unmatched ENDC 

266 Error in SETC 

267 UnteriDinated conditional conpilation option 

I-L5 Compiler Specific Limitations 

300 Too many nested record scopes 

301 Set limits out of range 

302 String limits out of range 

303 Too many nested procedures/functions 

304 Too many nested include/uses files 

305 Incluctes not alloied in interface secticm 

306 Pack and unpack are not implemented 

307 Too many units 

308 Set constant out of rar^ 

309 Structure too large ( > 32K ) 

310 Parameter list too large ( >= 32K ) 

350 Procedure too large 

351 File name in option too long 

K6 I/DEnon 

400 Not enough room for code file 

401 Error in rereading code file 

402 Error in reopening text file 

403 Unable to open uses file 

404 Error in reading uses file 

405 Error in opening include file 

406 Eror in rereading previously read text block 

407 Not enough room for I -code file 

408 Error in witing code file 

409 Error in reading I-code file 

410 Unable to open listing file 
420 I/O error on debug file 

K7 Clascal Enors 

800 OF missing 

801 Superclass Identifier missing 

802 Method NEW is not declared 

803 Subclass declaration not alloiied here 

804 Method is not a procedure 

805 Method is not implemented 

806 Class is not implemented 

807 Superclass identifier is not a class 

808 Identifier is not a class 
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809 'NEUI' not allowed here 

810 '^EW• was expected here 

811 Illegal •^EW• method 

812 Illegal use of class Identifier 

813 Unsafe use of a handle in an assignment statement 

814 Unsafe use of a handle in a WITH statement 

815 Unsafe use of a handle as a var parameter 

K8 Code Generation Enon 

1000-1999 Internal code generation errors 

2000 End of I -code file not found 

2001 Expression too complicated^ code generator ran out of registers 

2002 Code generator tried to free a register that was already free 
2003-2005 Error in generating address 

2006-2010 Error in expressions 

2011 Too many globals 

2012 Too many locals 

K9 Verification Errors 

4000 Bad verification block format 

4001 Source code version conflict 

4002 Compiler version conflict 

4003 Linker version conflict 

4100 Version in file less than minimum version supported by program 

4101 Version in file greater than maximum version supported by program 
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Appendix I 
Pascal Workshop Files 



This appendix lists the files on the Pascal 1.0 diskettes. 



File Name 


Pascal 


Notes 


Description 


Diskette 






Assembler. odj 


2 




Workshop program. 


BYE. TEXT 


1 




Workshop Installation exec file 


ByteDiff.obj 


3 




utility program. 


Changeseg.oDJ 


2 




Utility program. 


Ci start. text 


1 




Workshop installation exec file 


CISTARTl.TEXT 


1 




Workshop installation exec file 


Code. Ob j 


2 




Workshop program. 


coaesize.obj 


2 




Utility program. 


Olff.obJ 


3 




utility program. 


DunpoDj.odJ 


2 




Utility program. 


OunpPatch.obj 


3 




utility program. 


EDIT. MENUS. TEXT 


3 




Editor support file. 


Editor. Ob j 


5 




Workshop program. 


Flledlv.obj 


3 




Utility program. 


File join. Ob j 


5 




utility program. 


find. Ob J 


3 




Utility program. 


FhDATA 


1 


1.2 


Data segment. 


font.heur 


1 


1,2,3 


Data needed to support SYSlLib. 


FONT.HEUR 


3 




Second copy of same file. 


font. lib 


1 


1,2,3 


Data needed to support SYSlLlb. 


GETPROFILELOC.TEXT 


1 




Workshop installation exec file 


6ETYESN0.TEXT 


1 




Workshop installation exec file 


Gxref.obj 


2 




utility program. 


INSERTDISK.TEXT 


1 




workshop installation exec file 


Intrinsic. lib 


1 


2,3 


Library directory. 


lOSFplib.obJ 


3 




Library unit w/interface. 


lOSPaslib.obj 


1 


2,3 


Library unit w/interface. 


LDSPREFERENCES.OBJ 


3 




Workshop program. 



Note 1: These files are identical to Office System Release 1.0 files. 

Note 2: These files are identical to Office System Release 1.2 files. Office System 
1.2 is functionally identical to Office System 1.0, but is released to ensure 
compatibility with Pascal 1.0, BASIC-Plus 1.0, and COBOL l.a 

Note 3: These files are the minimtm necessary to run a user program in the 

workshop envlronmenu A user program may require other flies as well. 
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File Name 


Pascal 


Notes Description 


Diskette 




LOS_RES_PROCS.TEXT 


3 


Workshop data. 


Linker. Ob j 


2 


Workshop program. 


N68k.err 


2 


Assembler data. 


N68K. opcodes 


2 


Assembler data. 


Objiolib.obj 


2 


Library unit (no interface). 


OSERRS.ERR 


1 


3 Workshop data. 


PAPER. TEXT 


3 


Workshop data. 


Pascal. Ob j 


2 


Workshoia program. 


PASERRS.ERR 


2 


Workshop data. 


PASLIBCALL.OBJ 


2 


Library unit w/interface. 


Portconfig.obj 


3 


Utility program. 


Q0/B0XES.08J 


2 


Quickdraw sample program. 


OO/BOXES.TEXT 


2 


Quickdraw sample program. 


QD/FM68K.0BJ 


2 


QuickDraw unit (no interface) 


QO/F0NTM6R.OBJ 


2 


QuickDraw iffiit w/interferc^. 


gO/GRAF30.08J 


2 


QuickDraw unit w/interface. 


Q0/6RAFLIB.0BJ 


2 


QuickDraw unit (no interface) 


gO/GRAFTYPES.TEXT 


2 


Quickdraw assembly interfaces 


QO/GRAFUTIL.OBJ 


2 


QuickDraw unit w/interface. 


QD/HAROWARE.OBJ 


2 


Hardware unit w/interface. 


QD/HWINTL.OBJ 


2 


Hardware unit (no interface). 


QO/M/BOXES.TEXT 


2 


Exec file. 


QO/M/gOSAMPLE.TEXT 


2 


Exec file. 


QD/QOSAMPLE.OBJ 


2 


Quickdraw sample program. 


QD/QOSAMPLE.TEXT 


2 


Quickdraw sample program. 


QO/QOSTUFF.TEXT 


2 


Quickdraw unit filenames. 


QO/QOSUPPORT.OBJ 


2 


QuickDraw unit w/interface. 


gO/QUICKDRAW.OBJ 


2 


QuickDraw unit w/interface. 


Q0/ST0RA6E.0BJ 


2 


QuickDraw unit w/interface. 


QD/UNIT68K.0BJ 


2 


QuickDraw unit (no interface) 


QO/UNITHZ.OBJ 


2 


QuickDraw unit w/interface. 


QO/UNITSTD.OBJ 


2 


QuickDraw unit w/interface. 


resiclent_channel 


1 


1,2,3 System data. 


Segmap.obj 


2 


Utility program. 


Shell. Workshop 


1 


3 Workshc^ main program. 


Sulib.obj 


1 


3 Library unit w/interface. 


Sxref.obj 


3 


Utility program. 



Note 1: These files are Identical to Office System Release 1.0 files. 

Note 2: These files are identical to Office System Release 1.2 files. Office System 
1.2 is functionally identical to Office System 1.0, but is released to ensure 
corr^tibility with Pascal 1.0, BASIC-Plus 1.0, and COBOL 1.0. 

Note 3: These files are the minimum necessary to run a user program in the 

Workshop environment A user program may require other files as well. 
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File Nbmb 


Pascal 


Notes 


Description 


Diskette 






SXREF.OhlT.TEXT 


3 




Data. 


Sysllib.obj 


1 


1,2,3 


Library units (no interface). 


SYS2LIB.0BJ 


3 


1,2,3 


Library units (no interface). 


SYSCALL.OBJ 


2 




Library unit «/ interface. 


SYSTEH.BT PROF 




1,2,3 


System support. 


SYSTEM. BT TIIIG 




1,2,3 


System s(,ip|X)rt. 


SYSTEM. DEBUG 






WorksTiop program. 


SYSTEM. DEBUG2 






Itorkshop program. 


SYSTEM. lUDIRECTORY 




1,2,3 


System data. 


SYSTEM. LLD 




1,2,3 


System program. 


SYSTEM. LOG 




1,2,3 


System data. 


SYSTEM. OS 




2,3 


System program. 


System. Shell 




1,2,3 


System program. 


SYSTEM. STACKl 




1,2,3 


System data. 


SYSTEM. STACK2 




1,2,3 


System data. 


SYSTEM. STACK3 




1,2,3 


System data. 


SYSTEM. STACK4 




1,2,3 


System data. 


SYSTEM. SYSLOCl 




1,2,3 


System data. 


SYSTEM. SYSL0C2 




1,2,3 


System data. 


SYSTEM. SYSL0C3 




1,2,3 


System data. 


SYSTEM. SYSLX4 




1,2,3 


System data. 


SYSTEM. TIMER PIPE 




1,2,3 


System data. 


SYSTEM. UNPACK 




1,2,3 


System data. 


term. menus. text 


3 




Data for transfer program. 


transfer. Ob J 


3 




Vorkstmp program. 


Uxref.obj 


3 




Utility program. 


UXREF.UMAP.TEXT 


3 




Data for UXREF program. 


WMDATA 


1 


1,2 


Data segment. 


Xejectem.obj 


1 




Itorkshop installation program 


{T11}BUTT0NS 


3 


2 


Data. 


{T11}MENUS.TEXT 


3 


2 


Data. 



Note 1: These files are Identical to Office System Release 1.0 files. 

Note 2: These files are identical to Office System Release 1.2 files. Office System 
1.2 is functionally identical to Office System 1.0, but is released to ensure 
compatibility with Pascal 1.0, BASIC-Plus 1.0, and COBOL 1.0. 

Note 3: These files are the minimum necessary to run a user program in the 

Workshop environment A user program may require other files as well. 
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NOTES 



Index 



Please note that trie topic ref ereixies In this Index are by secUon number. 



abs function 11.4.2 
adcuracy in real arithmetic D 
actual -parameter 5.2^ 7.1, 7.3 

syntax 5.2 
actual-pararoeter-list 5.2 

syntax 5.2 
actual -parameters in procedure call 

6.1.2 
AddPt procedure E.9.17 
anomalies in Lisa Pascal B 
Apple II Pascal A 
Apple III Pascal A 
applestuff unit A 
arcs, graphic operations E.9.10 
arctan function 11.4.9 
arithmetic functions 11.4 
arithmetic operators 5.1.2, D 
array 3.2.1, 4.3.1 

conponent 3.2.1, 4.3.1 

reference 4.3.1 
array-type 3.2.1 

syntax 3.2.1 
ascent line E.5.2 
ASCII 3.1.1.5 

assembly lan^age, C^ickOraw E.ll 
assignment-conpatibility 3.4.3 
assigwient-statement 6.1.1 

syntax 6.1.1 



-B- 



BackColor procedure E.9.5 
BackPat procedure E.9.1 



base line E.5.2 
base-type 3.2.3, 3.3, 5.3 

of pointer-type 3.3 

syntax 3.3 

scope anomaly B 

of set-type 3.2.3, 5.3 
Beep procedure F.4 
bit image E.4.1 
bit transfer operations E.9.13 
BitHap data type E.4.2 
bitmaps E.4.2 

bitwise boolean operations A 
blank character 1.1 
blank segment 8.3, 9.1 
block 2 

syntax 2.1 
block-structured I/O 3.2.4, 

10.1.1-2, 10.4 
blockread function 3.2.4, 10.4.1 
block write function 3.2.4, 10.4.2 
boolean 3,1.1.4, 5.1.3, 5.1.5.2, 
10.3.3.7, 12.3-12.4 

comparisons 5.1.5.2 

constants as control values 12.3, 
12.4 

operands, evaluation of 5.1.3 

operators 5.1.3 

data type 3.1.1.4 

values in text-oriented output 
10.3.3.7 
boundry rectangle E.4.2 
Boxes program E.14.2 
buffer variable 10.1.3, 10.1.7 
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Index 



txjilt-in procedures & functions 10, 

11 
tMJsy cursor F.2.2 
BusyDelay procedure F.2.2 
Busy Image procedure F.2.2 
byte array 11.7 
byte-oriented procectires & functions 

11.7 
byte-size files 3.2.4 
bytestream type A 



camera eye E.12 
case 6.2.2.2 

syntax 6.2.2.2 
case-constant in case statement 

6.2.2.2 
case-sensitivity 1.1, 1.2, 1.4 
case-statement 6.2.2.2 

efficiency 12.5 

syntax 6.2.2.2 
char 1.6.1, 3.1.1.5, 10.3.1.1, 
10.3.3.2, 11.5 

constant 1.6.1 

type 3.1.1.5 

values in text-oriented I/O 
10.3.1.1, 10.3.3.2 
character 1.1, 3.2.4, 4.3.1 

device 3.2.4, 10.1.1-2 

files 3.2.4 

font E,5.2 

in string 4.3.1 

set 1.1 
character style E.5.2 
CharWidth function E.9.4 
chr function 11.5.2 
Clip30 function E.12. 4 
ClipRect procedure E.9.1 
clipRgn E.5 



clock/calendar F.8, F.9 
close procedure 10.1.5 
ClosePicture procedure E.9.14 
ClosePoly procedure E.9.15 
ClosePort procedure E.9.1 
CloseRgn procedure £.9.11 
closing a file 10.1.5 
code generation 12.1 
color drawir^ E.7.2 

routines E.9.5 
ColorBit procechjre E.9.5 
comment 1.8 
conparisms 5.1.5 
conpatibility of parameter lists 

7.3.5 
conpatible types 3.4 
cofflpile-time expressions & variables 

12.2.1-3 
conpiler 1.8, 12, A 

commands 1.8, 12.1-2, A 
cofiponent of array 3.2.1, 4.3.1 
conponent of file 3.2.4, 4.3.3 
coirponent-type of array 3.2.1 
component-type of file 3.2.4 
confxxjnd-statement 6.2.1 

syntax 6.2.1 
concat function 11.6.3 
conditional compilation 12.2 
conditional-statement 6.2.2 

syntax 6.2.2 
constant 1.4-7 

syntax 1.7 
constant-declaration 1.7, 2.1, B 

scope anomaly B 

syntax 1.7 
constant-declaration-part 2.1 

syntax 2.1 
constants, assembly language E.11.1 
contrast control F.3.1 
Contrast function F.3.1 
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index 



control -variable 6.2.3.3 

syntax 6.2.3.3 
coordinate plane E.3.1 
coordinates, grafPort E.3.1, E.6 
copy function 11.6.4 
CopyBits procedure E.9.13 
CqDyRgn procedure E.9.11 
cos function 11.4.5 
CR character 1.1, 1.6, 10.3 

in text-oriented I/O 10.3 
crunch 10.1.5 
current block nurtjer 10.4 
current file position 4.3.3 
cursor control 10.3.7, F.2 
Cursor data type E.4.4 
cursor-handling routines E.9.2 
CursorHeight data type F.io 
Cur sorl mage procedure F.2 
CursorLocation procedure F.2.1 
CursorPtr data type F.IO 
cursors, QuickDraw E.4.4 
CursorTraidcing procedure F.2.1 
customizing QuickDraw operations 

E.IO 



data bitmap F.2 
data types 3 
assenfcly language E.11.2 
6raf3D E.12.3, E.13.5 
QuickDraw E.2.2, E.13.2 
datafile 10.1.2 
date F.8, F.9 
DateArray data type F.IO 
DateTime procedure ? ,Z 
OateToTime procedure F.8 
dead key diacriticals F.5.4 
debugging 12.1 



defining declaration 7.1 
delete procetljre 11.6.5 
descent line E.5.2 
device 10.1.1-2 

character 10.1.1, 10.1.2 

file-structured 10.1.1, 10.1.2 

types 10.1.1, 10.1.2 
diacritical marks F.5.4 
DiffRgn procedure E.9.11 
digit 1.1 
digit- sequence 1 .4 

syntax 1.4 
DimContrast function F.3.2 
dimensions of Lisa screen E.4.1 
directive 1.3 

diskette insertion switches F.5 
display screen F.3 
DisposeRgn procedure E.9.11 
div operator A 
division by zero (real arithmetic) 

3.1.1.3, D 
OLE character 10.3 
DrawChar procedure E.9.4 
drawing E.7 

color ':.7.2 
DrawPicture prccedure E.9.14 
Drawstring procedire E.9.4 
DrawText procedure E.9.4 
dynamic allocation procedures 11.2 



efficiency, case-statements 12.5 
empty set 5.3 
EmptyRect function E.9.6 
EnptyRgn function E.9.11 
enumerated- type 3.1.2 
syntax 3.1.2 
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eof function 10.1.7 
and various procedures 10 . 1 . 3- A, 

10.1.7, 10.2.1-2, 10.2.4, 

10.3.1-2, 10.4.1 
eoln function 10.3.5 
and read and readln procechjres 

10.3.1, 10.3.2 
EqualPt function E.9.17 
EqualRect function E.9.6 
EqualRgn function E.9.11 
EraseArc procedure E.9.10 
EraseOval procedure E.9.8 
ErasePoly procedure E.9.16 
EraseRect procedure E.9.17 
EraseRgn procedure E.9.12 
EraseRoundRect procedure E.9.9 
ETX character A 
exit procechjre 11.1.1, A 
exp function 11.4.6 
expression 5 

syntax 5 
extended conparisons A 
external file 10.1 
external function 7.2 
external procedure 7.1-2 



factor 5 

syntax S 
FadeDelay function F.3.2 
field of record 3.2.2, 4.3.2, 6.2.4 
field-declaration 3.2.2 

syntax 3.2.2 
field-designator 4.3.2 

syntax 4.3.2 
field-list 3.2.2 

syntax 3.2.2 



file 3.2.4, 4.3.3> 10 

tDUffer 4.3.3 

buffer and eof function 10.1.7 

txiffer and reset proc«lire 10.1.3 

component 3.2.4, 4.3.3 

identifier as parameter type 7.3 

of char 3.2.4 

position and reset procedure 
10.1.3 

record 10.2 

reference 4.3.3 

species 10.1.2 

standard file-type identifier 
3.2.4, 10.1, 10.4 

types and reset procedure 10.1.3 

variable 3.2.4, 4.3.3, 10 
file-buffer-syntx)l 4.3.3 

syntax 4.3.3 
file-structured device 3.2.4, 

10.1.1-2, 10.4 
file- type 3.2.4 

syntax 3.2.4 
FillArc procedure E.9.10 
fillchar proceckjre 11.8.3 
FillOval procedure E.9.8 
FillPoly procedure E.9.16 
F i llRect procedure E . 9 . 7 
FillRgn procedure E.9.12 
FillRoundRect procedure E.9.9 
final-value 6.2.3.3 

syntax 6.2.3.3 
finite real values 3.1,1.3 
fixed-part 3.2.2 

syntax 3.2.2 
f ixed-|X)int output of real value 

10.3.3.4 
floating-point arithmetic D 
floating-point output of real value 

10.3.3.4, A 
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font numbers E.15 

fonts E.5.2 

for- statement 6.2.3.3 

syntax 6.2.3.3 
ForeColor procedure E.9.5 
foreign characters F.5.4 
formal-parameter-list 7.3 

syntax 7.3 
formal-parameters and procedure call 

6.1.2 
forward declaration 7.1-2 
FraiieArc procecAjre E.9.10 
FrameCouiter function F.3 
FrameOval procedure E.9.8 
FramePoly procedure E.9.16 
FrameRect procedure E.9.7 
FrameRgn procedure E.9.12 
FrameRouncffJect procedure E.9.9 
Frames data ty|:« F.IO 
function 7.2-3 
function-body 7.2 

syntax 7.2 
function-call 5, 5.2, 7.2, 7.3 

syntax: 5.2 
f mction-declaration 7 ,2 

syntax 7.2 
function-heading 7 . 2 

syntax 7.2 
functional parameter 7.3.4 
functions, asseirtbly language E.11.4 



get procedure 10.2.1, 10.2.3 
GetClip procedure E.9.1 
GetFontlnfo procedure E.9.4 
GetPen procedure E.9.3 
GetPenState procedure E.9.3 
GetPixel function E.9.18 
GetPort procedure E.9.1 



GetPort30 procedure E.12.4 
global coordinates E.6, E.9.17 
global variables, assembly language 

E.11.3 
GlobalToLocal procectire E.9.17 
goto- statement 6.2, A 

syntax 6.1.3 
gotoxy procedure 10.3.7.2 
Graf 30 E.12 

data types E.12.3, E.13.5 

sample program E.14.2 
Graf Device procedure E.9.1 
grafPort coordinates E.3.1, E.6 
Graf Port data type E.5 
grafPort routines E.9.1 
graf Ports E.5 
GrafPtr data type E.5 
Graf Verb data type E.IO 
graphics pen E.5.1 
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halt procedure 11.1.2, A 
handles E.3.4 

picture E.8.1 

polygon E.8.2 

region E.3.4 
hardware interface F 
heap 11.2 

heapresult function 11.2.2 
hex-digit 1.1 
hex-digit-sequence 1 . 4 

syntax 1.4 
hexadecimal constants 1.4 
HideCursor procedure E.9.2 
HidePen procedure E.9.3 
host program or unit 9 
host-type of subrange 3.1.3 
hotspot E.4.4, F.2 
hourglass cursor F.2. 2 
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identical types 3.4 
identifier 1.2 

of program 8.1 

syntax 1.2 
identifier-list 3.1.2 

syntax 3.1.2 
Identity procedure E. 12.4.2 
IEEE Floating-Point Standard D 
if -statement 6.2.2.1 

optimization 12.3 

syntax 6.2.2.1 
implementation-part 9.1.1 

syntax 9.1.1 
in operator 5.1.5.5 
index 4.3.1 

in variable-reference 4.3.1 

syntax 4.3.1 
index- type 3.2.1 

syntax 3.2.1 
infinities 3.1.1.3, D 
InitCursor procedure E.9.2 
InitGraf procedure E.9.1 
initial-value 6.2.3.3 

syntax 6.2.3.3 
initialization-part A 
InitPort procedure E.9.1 
input (standard file) 10.1.7, 10.3 
input file control (in compilation) 

12.1 
input variables in read procedure 

10.3.1 
input/output 10 
insert procedure 11.6.6 



InsetRect procedure E.9.6 
InsetRgn procedure E.9.11 
integer 1.4, 3.1.1.1-2, 10.3.1.2, 
10,3.3.3, 11.3-5, D 

arithmetic 3.1.1.1, 3.1.1.2 

constant 1.4 

conversion overflow D 

data type 3.1.1.1, 3.1.1.2 

data type conversions 3.1, 
3.1.1.5, 3.1.2, 11.5.1 

values in text-oriented I/O 
10.3.1.2, 10.3.3.3 
interactive file- type A 
interface-part 9.1.1 

syntax 9.1.1 
intrinsic-unit 9.2 
INTRINSIC. LIB 9.2, 12.1 
invalid operations in real arithmetic 

D 
InvertArc procedure E.9.10 
InvertOval procedure E.9.8 
InvertPoly procedure E.9.16 
InvertRect procedure E.9.7 
InvertRgn procedure E.9.12 
InvertRoLffTdRect procedure E.9.9 
ioresult function 10.1.2, 10.1.6 



key state F.5.3 
KeylxEvent function F.5.3 
KeybdId data type F.IO 
KeybdPeek function F.5.3 
KeybdOIndex data type F.IO 
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keytDoard 3.2. A, 10.1.1, 10.3, 
10.3.7.1, F.5 

attributes F.5.1 

echoing on input 10.3 

events F.5, F.5. 3 

identification F.5.1 

layouts F.5.1 

legends F.5.1 

physical 3.2.4, 10.1.1, 10.3, 
10.3.7.1 

queue F.5. 3 

repeats F.5. 5 

state F.5. 2 

testing 10.3.7.1 
Keytxjard function F.5.1 
Keycap data type F.IO 
KeyCapSet data type F.io 
keycodes F.5 
KeyEvent data type F.IO 
KeylsOown function F.5. 2 
Keyttap procedure F.5. 2 
keypress function 10.3.7.1 
KillPicture procedure E.9.U 
KillPoly procedure E.9.15 



label 1.5, 2.1, 6 

on stat«nent 6 

syntax 2.1, 6 
label-declaration-part 2.1 

syntax 2.1 
Legends function F.5.1 
length attribute 3.1.1.6 
length function 11.6.1 
letter 1.1 
Line procedure E.9.3 
line-drawing routines E.9.3 
Line20 procedure E.12.A 
Line30 procedure E.12.4 



LineTo procedure E.9.3 
LineTo20 procedure E.12.4 
LineTo30 procedure E.12.4 
Linker 7.1 
listing control 12.1 
In function 11.4.7 
local coordinates E.6, E.9.17 
LocalToGlobal procedure E.9.17 
lock 10.1.5 

long integer data type A 
longint 1.4, 3.1.1.2, 10.3.1.2, 
10.3.3.3, 11.3-5, D 
arithmetic 3.1.1.2 
constant 1.4, 1.6, 1.7 

11.3.4 
data type 3.1.1.2 
data type conversions 11.3.3, 
values in text-oriented I/O 
10.3.3.3 
LookAt procedure E. 12.4.1 
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ManyPixels data type F.lO 
MapPoly procedure E.9.18 
MajDPt procedure E.9.18 
HafDRect prcxiedure E.9.18 
MapRgn procedure E.9.18 
mark procedure 11.2.5, A 
mask bitmap F.2 
maxint 3.1.1.1 
uiemavail function 11.2.5 
member-group 5.3 

syntax 5.3 
memory allocation procedures 11.2 
microsecond timer F.6 
Microseconds data type F.lO 
MicroTimer function F.6 
millisecond timer F.7 
miliSeconds data type F.lO 



Index-7 



Pascal Reference Manual 



Index 



missing symbol E.5.2 
nod operator A 
mouse F.l 

txitton F.5 

plug F.5 
MouseLocation procedure F.l.t 
HouseOdORieter procedure F.1.4 
MouseScallng procedure F . 1 . 3 
MouseThresh procedure F.l. 3 
MouseUpdates procedure F.l. 2 
Move procedure E.9.3 
Move20 procedure E.12.4 
Move30 procedure E.12.4 
moveleft procedure 11.7.1 
MovePortTo procedure E.9.1 
raoveright procedure 11.7.2 
MoveTo procedure E.9.3 
MoveTo20 procedure E.12.4 
ho\/eTo30 procedure E.12.4 



N 

NaNs 3.1.1.3, D 

new procedure 3.3, 11.2.1, A 

NewRgn function E.9.11 

nil 3.3, 4.3.4, 11.2.1 

Noise procedure F.4 

normal 10.1.5 

nunOer 1.4 

numerical conf^risons 5.1.5.1 



object file 9 
c^ject of pointer 4.3.4 
ObscureCursor procedure E.9.2 
odd function 11.4.1 
OffsetPoly procedure E.9.15 
Of f setRect procedure E . 9 . 6 
OffsetRgn procedure E.9.11 



Open30Port procedure E.12.4 
opening a file 10.1, 10.1.2-4 
OpenPicture function E.9.14 
OpenPoly function E.9.15 
OpenPort procedure E.9.1 
OpenRgn procedure E.9.11 
operands 5 

coii|)ile-time 12.2.3 

in expressions 5 
operators 5 

compile-time 12.2.3 

in expressions 5 
optimization of if, repeat, and «»hile 

statements 12.3, 12.4 
ord function 3.1, 3.1.1.5, 3.1.2, 

11.5.1 
ord4 function 3.1.1.2, 11.3.3 
order of evaluation of operands 

5.1.1 
ordinal functions 11.5 
ordinal-type 3.1 

and ord function 11.5.1 

and ord4 function 11.3.3 

aid pred function 11.5.4 

and succ function 11.5.3 

syntax 3.1 
ordinal-type-identifier 3 
ordinality 3.1 
otherwise-clause 6.2.2.2 

syntax 6.2.2.2 
ou^jut (standard file) 10.3 
output expression in write procedure 

10.3.3 
output file in write procedure 

10.3.3 
output-specs in write proceAire 

10.3.3 
ovals, gr^ic operations E.9.8 
overflow (real arithmetic) 

3.1.1.3, D 
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packed array of char 5.1.5.6, 
10.3.1.5, 10.3.3.6, 11.8 
coiparisons 5.1.5.6 
fillchar procedure 11.8.3 
scanning functions 11.8.1, 11.8.2 
text-oriented I/O 10.3.1.5, 
10.3.3.6 

packed data types 3.1.1.6, 3.2 

page procedure 10.3.6 

PaintArc procedure E.9.10 

PaintOval procedure E.9.8 

PaintPoly procedure E.9.16 

PaintRect procedure E.9.7 

PaintRgn procedure E.9.12 

PaintRoundRect procedure E.9.9 

parameter 7.1, 7.3 

parameter list conpatibility 7.3.5 

parameter-declaration 7.3 
syntax 7.3 

parameters in procedure call 6.1.2 

Pascal conpiler 12 

Pattern data type E.4.3 

pattern transfer mode E.7.1 

patterns E.4.3 

pen E.5.1 

pen routines E.9.3 

PenMode procedure E.9.3 

Penttormal procedure E.9.3 

PenPat procedure E.9.3 

PenSize procedure E.9.3 

performance pereilty for longint 
values 3.1.1.2 

PicComment procedure E.9.14 

PicHandle data type E.8.1 

PicPtr data type E.8.1 

picture ccMnments E.8.1 

Picture data type E.8.1 

picture frame E.8.1 

picture routines E.9.14 



pictures E.8.1 

Pitch procedure E.12.4.2 

pixel E.4.1 

Pixels data type F.lO 

Point data type E.3.2 

pointer 4.3.4, 11.2 

pointer function 3.3, 11.3.4 

pointer-Ob ject-syntxDl 4.3.4 

syntax 4.3.4 
pointer-reference 4.3.4 
pointer-type 3.3 

conversions 11.3.3, 11.3.4 

syntax 3.3 
pointer-type-identifier 3 
points E.3.2 

points, calculations E.9.17 
Polygon data type E.8.2 
polygons E.8.2 

calculations E.9.15 

grsphic operations E.9.16 
Polyftendle data type E.8.2 
PolyPtr data type E.8.2 
portBits E.5 
portRect E.5 
PortSize procedure E.9.1 
pos function 11.6.2 
power switch F.5 
precedence of operators 5 
pred functiai 3.1, 11.5.4 
predecessor 3.1 
procedural parameter 7.3.3 
procedure 7.1, 7,3 
prcxiedure-and-function-declaration- 
part 2.1 

syntax 2.1 
procedure-body 7 . 1 

syntax 7 . 1 
procedure-declaration 7.1 

syntax 7.1 
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procedure-heading 7 . 1 

syntax 7.1 
procedure-statement 6.1.2, 7.1 

syntax 6.1.2 
prcx^dures^ assetiOly language 
program 8 

identifier 8.1 

segments 8.3 

syntax 8.1 
program-heading 8 . 1 

syntax 8.1 
program-parameters 8.1^ 

syntax 8.1 
Pt2Rect procedure E.9.6 
PtInRect function E.9.6 
PtInRgn function E.9.11 
PtToAngle procedure E.9.6 
purge 10.1.5 
put procedure 10.2.2-3 
pwroften function 11.4.10 
pyramid E . 12 



E.11.4 



8.2 



QOProcs data type E.IO 
QOProcsPtr data type E.IO 
QDSample program E.2.1, E.14.1 
QOSupport unit E.IS 
qualifier 4.3 
syntax 4.3 
QuickDraw E 

QuickDraw data types E.2.2, E.13.2 
QuickDraw glossary E.16 



QuickDraw routines E.9 

arcs E.9. 10 

bit transfer E.9. 13 

color drawing E.9. 5 

cursor handling E.9. 2 

customizing E.IO 

graf Ports E.9.1 

line drawing E.9. 3 

miscellaneous utilities E.9. 18 

ovals E.9. 8 

pen E.9. 3 

pictures E.9. 14 

points E.9. 17 

polygons E.9. 15, E.9. 16 

rectangles E.9.6, E.9. 7 

regions E.9.11, E.9. 12 

rounded-comer rectangles E.9. 9 

text drawing E.9. 4 

wedges E.9. 10 
QuickDraw sanple programs E.2.1, 

E.14 
QuickDraw sunmary E.13 
QuickDraw, using from assenOly 

language E.ll 
quoted-character-constant 1.6.1 

syntax 1.6.1 
quoted-string-constant 1 . 6 

syntax 1.6 
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RarnDContrast procedure F.3.1 
Random function E.9. 18 
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range-ctiecking 3.1.3, 12.1 
read procedure 10.3.1 
readin procedure 10.3.2 
real 1.4, 3.1.1.3, 10.3.1.3, 
10.3.3.4, 11.3-4, D 

arithmetic D 

constait 1.4 

data type 3.1.1.3, D 

data type and round function 11.3.2 

values 3.1.1.3 

values end write procedure D 

values in text-oriented I/O 
10.3.1.3, 10.3.3.4, 
real -type 3.1 

syntax 3.1 
real-type-identifier 3 
record 3.2.2, 4.3.2 

field 3.2.2, 4.3.2 

nuntjer aid seek procedure 10.2.4 

of file 10.2 

reference 4.3.2 

reference in with statement 6.2.4 
record-oriented I/O 10.2 
record- type 3.2.2 

new procedure 11.2.1 

syntax 3.2.2 
rectangle calculation routines E.9.6 
Rectangle data type E.3.3 
rectangles E.3.3 

gr^ic operations E.9.7 
Rectlrtf^gn function E.9.11 
RectRgn proDeckire E.9.11 
recursion 7.1-2 
redeclaration of identifier 2.2.2, 

2.2.4 
Region data type E.3.4 
regions E.3.4 

calculations E.9.11 

graphic operations E.9.12 
regular-unit 9.1 

syntax 9.1.1 



relational operators 5.1.5 
release procedure 11.2.4, A 
repeat- statement 6.2.3.1 

optimization 12.4 

syntax 6.2.3.1 
repeating keys F.5.5 
RepeatRate procedure F.5.5 
repetitive-statement 6.2.3 

syntax 6.2.3 
reserved words 1.1 
reset procedure 10.1, 10.1.5, A 
result-type 7.2 

syntax 7.2 
rewrite procedure 10.1.4 
RgnHarxlle data type E.3.4 
RgnPtr data type E.3.4 
Roll procedure E.12.4.2 
rotation E.12 
rcMJTd function 11.3.2, D 
rounded-corner rectangles E.9.9 
rounding in real arithmetic D 
row width E.4.1 



Scale procedure E.12.4.2 
scale-factor 1.4 

syntax 1.4 
ScalePt procedure E.9.18 
scan function A 
scaneq function 11.8.1 
scanne function 11.8.2 
scope 2.2 

of standard objects 2.2.5 
screen 10.3, 10.3.7.2, F.3 

contrast F.3.1 

cursor control 10.3.7.2, F.2 

fading F.3. 2 

physical 10.3 
ScreenContrast data type F.IO 
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ScreenSize procedure F.3 

ScrollRect procechjre E.9.13 

Seconds data type F.IO 

SectRect function E.9.6 

SectRgn procedure E.9.11 

seek procedure 10.2.3 

segment keyword A 

segmentation 8.3 

segments 8.3, 9.1, 9.2.1 

selector in case statement 6.2.2.2 

set 3.2.3, 5.1.4, 5.1.5.4, 5.3 

comparisons 5.1.5.4 

membership testing 5.1.5.5 

operators 5.1.4 

values 5.3 
set-constructor 5, 5.3 

syntax 5.3 
set-type 3.2.3 

syntax 3.2.3 
SetClip procedure E.9.1 
SetContrast procedure F.3.1 
SetCursor procedure E.9.2 
SetDateTime procedure F.8 
SetDimContrast procedure F.3. 2 
SetEmptyRgn procedure E.9.11 
SetFadeDelay procedure F.3. 2 
SetLegends procedure F.5.1 
SetOrigin procedure E.9.1 
SetPenState procedure E.9.3 
SetPort procedure E.9.1 
SetPort30 procedure E.12.4 
SetPortBits procedure E.9.1 
SetPt procedure E.9.17 
SetPt20 procedure E.12.4 
SetPt30 procedure E.12.4 
SetRect procedure E.9.6 
SetRectRgn procechjre E.9.11 
SetRepeatRate procedure F.5.5 
SetStdProcs procedure E.IO 
SetTimeStanp procedure F.9 



SetVolume procedure F.4 
ShowCursor procedure E.9.2 
ShowPen procedure E.9.3 
sign 1.4 

syntax 1.4 
signed zero 3.1.1.3 
signed-number 1.4 

syntax 1.4 
Silence procedure F.4 
simple-expression 5 

syntax 5 
sinple- statement 6 . 1 

syntax 6.1 
sinple-type 3.1 

syntax 3.1 
simple-type- identifier 3 
sin function 11.4.4 
size-attribute 3.1.1.6 

syntax 3.1.1.6 
sizeof function 11.7.3 
Skew procedure E.12.4. 2 
source transfer mode E.7.1 
SpaceExtra procedure E.9.4 
speaker F.4 

sJDeakerVolume data type F.lO 
special symbols 1.1 
sqr function 11.4.3 
sqrt function 11.4.8, D 
stack space and memavail function 

11.2.5 
standard procedures and functions 

for I/O 10 

10, 11 
standard simple-types 3.1 
statement 6 

syntax 6.1 
statement-part 2 . 1 

syntax 2 . 1 
StdArc procedure E.IO 
StdBits procedure E.IO 
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StdComment procedure E.IO 
StdGetPic procedure E.IO 
StdLine procedure E.IO 
StdOval procedure E.IO 
StdPoly procedure E.IO 
StdPutPic procedure E.IO 
StdRect procedure E.IO 
StcffJgn procedure E.IO 
StdText procedure E.IO 
StdTxMeas function E.IO 
string 1.6, 3.1.1.6, 4.3.1, 5.1.5.3, 
10.3.1.4, 10.3.3.5, 11.6, A 

character 4.3.1 

coirparisons 5.1.5.3 

concatenation 11.6.3 

constant 1.6, 3.1.1.6 

constant comparisons 5.1.5.3 

length function 11.6.1 

procedures and functions 11.6 

reference 4.3.1 

substring copying 11.6.4 

substring deletion 11.6.5 

substring insertion 11.6.6 

substring search 11.6.2 

values in text-oriented I/O 
10.3.1.4, 10.3.3.5 
string-character 1.6 

syntax 1.6 
string-type 3.1.1.6 

syntax 3.1.1.6 
string-type-identifier 3 
Stringttlidth function E.9.4 
structured- statement 6 . 2 

syntax 6.2 
structured-type 3.2 

syntax 3.2 
structured-type-identifler 3 
Stuff ftex procedure E.9.18 
SLtoPt procedure E.9.17 



subrange-type 3.1.3 

syntax 3.1.3 
succ function 3.1, 11.5.3 
successor 3.1 
syntax diagrams, corrplete collection 

C 
syntax diagrams, explanation Preface 
system intrinsic library 9.2.2, 12.1 



tag constants in new and dispose 

procedures 11.2.1-2 
tag-field 3.2.2 
tag-field-type 3.2.2 

syntax 3.2.2 
term 5 

syntax 5 
testing set membership 5.1.5.5 
text E.5.2 

text type 3.2.4, 10.1.2, 10.3 
text-drawing routines E.9.4 
text-oriented I/O 10.3 
TextFace procedure E.9.4 
textfile 10.1.2, 10.3, A 
textfile format 10.1.2, 10.3 
TextFont procedure E.9.4 
Text^^ode procedure E.9.4 
TextSize procedure E.9.4 
TextWidth function E.9.4 
three-dimensional graphics. See 

Graf 3D. 
time F.8, F.9 
time stanp F.9 
Timer function (millisecond timer) 

F.7 
timers F.6, F.7 
TimeStamp function F.9 
TimeToOate procedure F.9 
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trsnsfer functions 11.3 
transfer modes E.7.1 
TransForm procedure E. 12.4.2 
transformation matrix E.12 
Translate procedure E. 12.4.2 
treesearch procedure A 
trunc function 11.3.1^ \ D 
turtlegraphics unit A 
type 3 

conpatidility aid identity 3.4 

syntax 3 
type-declaration 3 

syntax 3 
type-declaration-part 2.1^ 3.5 

syntax 2.1 
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UCSO Pascal A 

unary aritt^Mnetic operators 5.1.2 
Loiderscore character A 
UnionRect procedure E.9.6 
UnionRgn procedure E.9.11 
unit 9 

intrinsic 9.2 

regular 9.1 
unit-heading 9.1.1 

syntax 9.1.1 
unsigned-constant 5 

syntax 5 
unsigned-integer 1.4 

syntax 1.4 
unsigned-number 1.4 

syntax 1.4 
unsigned-real 1.4 

syntax 1.4 
untyped file 3.2.4, 10.1.1-2, 10.4 

I/O 10.4 
uses-clause 8.1, 9.1.1-2, 9.2, 9.3 

syntax 8.1 



value parameter 7.3.1 
variable 4 

variable parameter 7.3.2, A 
variable-declaration 4 . 1 

syntax 4.1 
variable-declaration-part 2 . 1 

syntax 2.1 
variable- identifier 4 . l 

syntax 4.1 
variable-reference 4.2 

syntax 4.1 
variant 3.2.2 

records, v&* procedure 11.2.1 

syntax 3.2.2 
variant-part 3.2.2 

syntax 3.2.2 
vertical retrace F.3 
VHSelect data type E.3.2 
ViewAngle procedure E. 12.4.1 
viewing pyramid E.12 
Viewport procedure E.12. 4.1 
visRgn E.5 
Volume function F,4 
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t*edges, graphic operations E.9.10 
while-statement 6.2.3.2 

optimization 12.4 

syntax 6.2.3.2 
with-statement 6.2.4 

syntax 6.2.4 
wordstream type A 
write procedure 10.3.3, A 

with real values D 
write-protection of file 10.1.5 
writeln procedure 10.3.4, A 
xForm matrix E.12 
XorRgn procedure E.9.11 
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Yaw procedure E.12.4.2 
zero, signed 3.1.1.3 



CHARACTERS 

$C conpiler cxMimatxIs 12.1 
$0 compiler connands 12.1 
$C€CL conpiler comnand 12.2.1 
$E conpiler conmand 12.1 
SELSEC conpiler command 12.2.4 
$EhOC conpiler command 12.2.4 
$1 conpiler conmand 12.1 
$IFC conpiler conmand 12.2.4 
$L conpiler commands 12.1 
$R conpiler commands 3.1.3, 12.1 
$S conpiler conmand 8.3, 9.1, 9.2, 

12.1 
$SETC conpiler conmand 12.2.1 
$U conpiler canmands 9.1.2, 9.2.2, 

12.1 
$X compiler conmands 12.1 
0, signed 3.1.1.3 
16-bit integer arithmetic 3.1.1.1-2, 

11.3.3 
32-bit integer arithmetic 3.1.1.2, 

11.3.3 
30 graphics. See Graf 30. 
a operator 3.3, 5.1.6 
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HIS MANUAL was produced using 

LisaWrite, LisaDraw, and 

LisaList. 



LL PRINTING was done with an 
Apple Dot Matrix Printer. 




theLisa'^ 

...we use it ourselves. 



Pascal Reference Manual Mail-Back Form 



Apple puDllcatlons would like to leam about readers and what you think about this 
manual in order to make better manuals In the future. Please fill out this form^ or 
write all over it, and send it to us, we promise to read it 

How are you using this manual? 

[ ] learning to use the product [ ] reference [ ] both reference and learning 

[ ] other 

Is it quick and easy to find the information you need in this manual? 
[ ] always [ ] often [ ] sometimes [ ] seldom [ ] never 

Connments 



What nnakes this manual easy to use?. 



What makes this manual hard to use? 



What do you like most about the manual?. 



What do you like least about the manual?. 



Please comment on, for example, accuracy, level of detail, number and usefulness of 
examples, length or brevity of explanation, style, use of graphics, usefulness of the 
index, organization, suitability to your particular needs, readability. 



What languages do you use on your Lisa? (check each) 

[ ] Pascal [ ] BASIC [ ] COBOL [ ] other 

How long have you been progrsmmlng? 



[ ] 0-1 years [ ] 1-3 [ ] 4-7 [ ] over 7 [ ] not a programmer 

What is your Job title? 

Have you completed: 

[ ] high school [ ] some college [ ] BA/BS [ ] MA/MS [ ] more 

What magazines do you read? 



other comnrents (please attach more streets if rrecessary). 



029-0406-A 



FUD 



FOLD 



PLACE 
HERE 



j^cippkz Gompubzr 

POS Publications Department 
20525 Marlanl Avenue 
Cupertino^ California 95014 



TfiK OR STAPLE 



